Standards

Summary

• Color palettes
• Code snippets
• Coding standards

Color palettes

In order to build a consistent look across the page elements, I've collected some famous color palettes and built a very useful html version which is very friendly for all of us who loves a copy and paste feature!

• 
  Tango Color Palette
• 
  Windows Theme Color Palette

Code snippets

Nowadays many editors like Notepad++, gEdit and Textmate, provide support for coding snippets. According to macromates: "A snippet is a piece of text that you would like to insert in your document. It can include code to run at insertion time, variables (like selected text), tab stops/placeholders for missing information (which you can tab through after insertion) and perform transformations on the data which you enter in the placeholders."

Although supporting editors bring some snippets with it. I usually don't like them simply because that was not the way I code. Since I'm often changing my programming language, a coherent convention between them is required. That's why I usually erase them and replace with the ones inside my Snippets Zip Package. The featured languages are:

• Global
• HTML (as XHTML 1.1 Strict)
• Javascript (with MOOTools)
• ASP
• PHP (with ZendFramework)
• SQL (MSSQL T-SQL)
• XML (enhanced with XSLT, SOAP)

Since keeping them up-to-date is vital for my work, I'll be putting all my efforts to keep this updated.

Coding standards

These are my coding standards, they are inspired by many works as Sun - Code Conventions for Java Programming Language, Douglas Crockford - Code Conventions for the JavaScript Programming Languag, ZendFramework - Coding Standards for PHP and Hungary Notation.

Coding standards are important in any development project, but they are particularly important when many developers are working on the same project. They help ensure that the code is high quality, has fewer bugs, and can be easily maintained.

1. File formatting
   1. File names
   2. Sufixes and Prefixes
   3. File extensions
   4. Indentation
2. Name conventions
   1. Classes, Objects and Structures
   2. Functions, Methods and Subroutines
3. Coding style
   1. Key and Reserved words
   2. Comments
   3. Constants
   4. Variables
   5. Basic-like syntax
   6. C-like syntax
4. Versioning
5. Documentation

File formating

File names

For all files, only alphanumeric characters, underscores, and the dash character ("-") are permitted. Spaces are prohibited.

Sufixes and Prefixes

Files holding classes should have a sufix .class which comes before the extension.

File extensions

Programs should be stored and delivered in the language standard extension. In other words, we expect:

• .js for JavaScript,
• .css for Cascading Style Sheet,
• .asp for Active Server Pages,
• .php for PHP Hypertext Preprocessor,
• .sql for Structured Query Language,
• .
• ... and so on ...
• .

Indentation

Indentation should consist of 4 spaces. Tabs are not allowed.

Name conventions

Classes, Objects and Structures

Class names may only contain alphanumeric characters. Numbers are permitted in class names but are discouraged.

If a class name is comprised of more than one word, the first letter of each new word must be capitalized. Successive capitalized letters are acceptable.

Functions, Procedures, Methods and Subroutines

Function names may only contain alphanumeric characters. Underscores are not permitted. Numbers are permitted in function names but are discouraged.

Function names must always start with a lowercase letter. When a function name consists of more than one word, the first letter of each new word must be capitalized. This is commonly called "camelCase" formatting.

Verbosity is encouraged. Function names should be as verbose as is practical to enhance the understandability of code.

These are examples of acceptable names for functions: helloWorld(), fooBar() and getElementById()

For object-oriented programming, accessors for objects should always be prefixed with either "get" or "set". When using design patterns, such as the singleton or factory patterns, the name of the method should contain the pattern name where practical to make the pattern more readily recognizable.

For methods on objects that are "private" or "protected", the first character of the variable name must be a single underscore. This is the only acceptable usage of an underscore in a method name. Methods declared "public" may never start with an underscore.

Functions in the global scope ("floating functions") are permitted but discouraged. It is recommended that these functions should be wrapped in a static class.

Coding style

Key and Reserved words

Keywords and Reserved-words are always in lowercase.

Comments

Be generous with comments. It is useful to leave information that will be read at a later time by people (possibly yourself) who will need to understand what you have done. The comments should be well-written and clear, just like the code they are annotating. An occasional nugget of humor might be appreciated. Frustrations and resentments will not.

It is important that comments be kept up-to-date. Erroneous comments can make programs even harder to read and understand.

Make comments meaningful. Focus on what is not immediately visible. Don't waste the reader's time with stuff like: i = 0; // Set i to zero.

Generally use line comments. Save block comments for formal documentation and for commenting out.

Constants

Numeric constants should not be coded directly. E.g. use adOpenForwardOnly instead of 0.

Constants may contain both alphanumeric characters and underscores. Numbers are permitted in constant names.

All letters used in a constant name must be capitalized.

Words in constant names must be separated by underscore characters. For example, EMBED_SUPPRESS_EMBED_EXCEPTION is permitted but EMBED_SUPPRESSEMBEDEXCEPTION is not.

Variables

All variables should be declared before used. Some languages doesn't required this, but doing so makes the program easier to read and detect undeclared variables that may become globals and trigger errors.

Basic-like syntax

conditional statements

if(condition) then
    statements
end if

if(condition) then
    statements
else
    statements
end if

if(condition) then
    statements
elseif(condition) then
    statements
else
    statements
end if

select case condition
    case VALUE
        statements
    case else
        statements
end select

looping statements

for(condition)
    statements
next

while(condition)
    statements
wend

do
    statements
loop until(condition)

parentheses

if(a = b and c = d) ' wrong
if( (a = b) and (c = d) ) ' right

C-like syntax

conditional statements

if(condition) {
    statements;
}

if(condition) {
    statements;
} else {
    statements;
}

if(condition) {
    statements;
} else if(condition) {
    statements;
} else {
    statements;
}

switch(condition) {
    case VALUE:
        statements;
        break;
    default:
        statements;
        break;
}

looping statements

for(initialization; condition; update) {
    statements;
}

while(condition) {
    statements;
}

do {
    statements;
} while(condition);

parentheses

if(a == b && c == d) // wrong
if( (a == b) && (c == d) ) // right

Versioning

Softwares should implement the "Version.Major.Minor.Build convention" for versioning. Version holds the number of attempts to solve the problem which is motivation for the software to be developed. It's usually related to a theorical model to attack the problem. Major will be incremented when something big, which can cause break of compatibility with the older version, is implemented. Minor will be incremented for every new feature that doesn't cause any problem for the older version. Build is a fix or something else.

Documentation

Natural docs is our current documenting system. It was selected because it's support for multiple programming languages enable us to provide the same look and feel accross different source-based documents. Click here to know more about using it.