Intermol Coding Standards (Standards) 
---------------------------------------------------------------------
    by Fulvio Oliveira, 2006-12-05 13:26 

/////////////////////////////////////////////////////////////////////
// intermol_coding_standards.txt
/////////////////////////////////////////////////////////////////////
// description
// 	the coding standards for Intermol Internet
/////////////////////////////////////////////////////////////////////
// requirements
//	none
/////////////////////////////////////////////////////////////////////
// important elements
//	information
/////////////////////////////////////////////////////////////////////
// produces
//	knowledge
/////////////////////////////////////////////////////////////////////
// history
//	+------------+-----------------+--------------------------+
//	| when       | who             | what                     |
//	+------------+-----------------+--------------------------+
//	| 2003-06-10 | fulvio oliveira | created the file         |
//	+------------+-----------------+--------------------------+
//	| 2006-11-05 | fulvio oliveira | first English version,   |
//	|            |                 | enhanced header and      |
//	|            |                 | minor corrections        |
//	+------------+-----------------+--------------------------+
/////////////////////////////////////////////////////////////////////


Abstract

	This document describes a recommended coding standard for
	HTML/CSS, JavaScript, PHP, ASP and SQL. It aims at coding
	style and functional organization.

	It's loosely based on the "Recommended C Style and Coding
	Standards" by the Bell Labs.


1. Introduction

	The standards in this document are required for all coding
	written for Intermol. Many of these choices are arbitrary,
	and chosen after the author's experience. The goal is to
	have all developers understanding easily each other's
	coding, for its indentation, commenting, naming, conventions
	and spacing are all commom to everybody's coding. All
	examples are PHP, you can work it out in your language.

	"To be clear is professional, not to be clear is
		unprofessional."
						Sir Ernest Gowers


2. File Organization

	A file consists of various sections that should be separated
	by several blank lines.


2.1. Number of Lines

	If possible, files should have as few lines as possible, from
	200 to 500 lines.


2.2. Number of Characters

	Though most of us are using Windows, it would be nice to have
	the lines shorter than 70 characters. Some of these codes
	are edited on servers without a graphical interface. Use
	longer lines only when absolutely necessary.


2.3. File Naming Conventions

	File names are made up of a base name, a period and a suffix.
	The first character of a name should be a letter. The whole
	name is to be in lower-case letters, and may also use numbers
	and underscore ( _ ).

	The following suffixes are required:

	* HTML files should end in .html
	* JavaScript should be always inside the HTML or included
		on the server side
	* PHP files should end in .php
	* ASP files should end in .asp


2.4. File Contents

	The requested itens on all files are:

	2.4.1. A header, which holds many information about the file
	itself, what it does, all important elements, who wrote and
	who edited the file. The standard is:

/////////////////////////////////////////////////////////////////////
// the name of the file
/////////////////////////////////////////////////////////////////////
// description
// 	a brief description of what this file is
/////////////////////////////////////////////////////////////////////
// requirements
//	everything that is necessary to run this file
/////////////////////////////////////////////////////////////////////
// important elements
//	the important elements used within the file
/////////////////////////////////////////////////////////////////////
// produces
//	elements or whatever the file creates/generates
/////////////////////////////////////////////////////////////////////
// history
//	a table, using this template, showing
//	+------------+--------+------------------+
//	| when       | who    | what             |
//	+------------+--------+------------------+
//	| date       | name   | what happened    |
//	+------------+--------+------------------+
/////////////////////////////////////////////////////////////////////

	Note that the lenght of the / lines is 70 characters. If the
	character / is not the default comment character, use the
	comment character instead. Eg, the header on this file.

	2.4.2. The required elements: included files, required
	objects, form objects, querystrings, etc. When coding, one
	should initially check for the existence and consistency of
	the required elements, preventing the file from execution
	and returning an error message if something is wrong. When
	the requirement of an element only happens deep into the
	code, make sure this element is on the header.

	2.4.3. All constants, definitions and functions, except for
	the ones created dinamically and destroyed within the file.
	Every function declared on the beginning should have it's
	own complete header, and should be treated as if it were a
	file itself. When possible, separate all functions into
	their own files, so we all could use it later.

	2.4.4. If the file is the entry point for the program
	(index.php, for instance), it should show 'the bigger
	picture' of the whole program: what it does, for whom it
	was developed, the basic file structure.

	Obs: do NOT include comments inside HTML coding, as they will
	be sent to the client machine. HTML should be kept clean, and
	it's comments, if necessary, should be kept in a separate
	offline file.


3. Comments

	"When the code and the comments disagree, both are
		probably wrong."
							Norm Schryer

	3.1. Avoid sendind them to clients!

	3.2. The comments should describe:
		3.2.1. What is happening;
		3.2.2. How it is being done (if not obvious);
		3.2.3. The parameters meanings;
		3.2.4. The elements used;
		3.2.5. The elements modified;
		3.2.6. The expected result;
		3.2.7. Restrictions, bugs and suggestions.

	3.3. Do not comment micrologic.

	3.4. Comments should justify offensive code.

	3.5. The indentation of the comment should follow that of
	the code itself, such as:

if ($money == 0) {
	// you are broke
	die('This purchase cannot be completed: lack of funds');
}


	3.6. The comment can be on the same line, as long as well
	indented. Other similar comments should have the same
	indentation.

if ($money >= $purchase) {
	$accepted = true;		// you can pay, go ahead
} else {
	$accepted = false;		// you are broke
}


	3.7. Blocks of code should have a very distinguishable
	begining and ending. Always use this comment style.

///////////
// begin ////////////////////////
// check if the user has money //
/////////////////////////////////

if ($money >= $purchase) {
	$accepted = true;
} else {
	$accepted = false;
}

/////////////////////////////////
// check if the user has money //
// end //////////////////////////
/////////


4. Function Declarations

	4.1. It is highly adviseable to have each function in its own
	file. When not possible, this function should be preceded by
	a block comment exactly like the file head comment listed in
	section 2.4. It's adviseable to have the discussion of non-
	trivial design decisions and side effects.

	4.2. The function return or break should be alone on a line,
	indented as necessary.


5. Whitespace

	5.1 The use of vertical and horizontal white space should be
	generous. Indentation and spacing should reflect the block
	structure of the code.

	5.2. Each statement should preferebly be on its own line.
	Closely related statements should be on adjacent lines, as
	a chunk. There should be at least 1 blank line between one
	chunk of code and the next one.

	5.3. If the code is a block statement that has a very
	distinguishable	begining and ending (see 3.7), there should
	be at least 5 blank lines between prior code and the begining
	comments and 5 blank lines between the rest of the code and
	the ending comments.

	5.4. A long string of contitional operators should be split
	into separate lines, such as:

	if 	(
		($money >= $purchase) and
		($user == 'fulvio') and
		($month != '12')
		) {
		return true;
	}

	Use the same idea for other long statements.

	5.5. Ternary operators should be avoided.

	5.6. Keywords that are followed by expressions in parenthesis
	should not be separated from the left parenthesis. It is
	adviseable, though, that if the number of arguments is too
	long, it should be broken into several lines, eg:

	mail(
		'contato@fulviooliveira.com.br',
		'<< your purchase was accepted >>',
		$message,
		$headers
	);

	The same should be applied for arrays:

	$week_days = array(
		1	=>	'Monday',
		2	=>	'Tuesday',
		3	=> 	'Wednesday',
		4	=>	'Thursday',
		5	=>	'Friday',
		6	=>	array(
			0	=>	'no work on saturday',
			1	=>	'religious day'
		),
		7	=>	'beach day'
	);

	5.7. There should be only one statement per line unless these
	statements are short and very closely related.

	case FOO:  oogle (zork);  boogle (zork);  break;
	case BAR:  oogle (bork);  boogle (zork);  break;
	case BAZ:  oogle (gork);  boogle (bork);  break;

	5.8. Mostly, avoid embedded assignment statements. In some
	situations where there is no better way to accomplish the
	results, such as:

	while ($result = mysql_fetch_assoc($query)) {
		process the resource...
	}


6. Compound Statements

	6.1. A compound statement is a list of statements enclosed by
	braces. The chosen way of formatting the braces is the
	"K&R style". The open brace should be on the same line as the
	statement, and the else part of an if-else statement and the
	while part of a do-while statement should appear on the same
	line as the close brace. The close brace should have the same
	indentation as the original statement.

	control {
	        statement;
	        statement;
	}

	6.2.  When a block of code has several labels (unless there
	are a lot of them), the labels are placed on separate lines.
	The fall-through feature of the PHP switch statement,
	(that is, when there is no break between a code segment
	and the next case statement) must be commented for future
	maintenance.

	switch (expr) {
		case ABC:
		case DEF:
			statement;
			break;
		case UVW:
			statement;
			/*FALLTHROUGH*/
		case XYZ:
			statement;
			break;
	}

	The last break is unnecessary, but is required because it
	prevents a fall-through error if another case is added later
	after the last one. The default case, if used, should be
	last and does not require a break if it is last.

	6.3. Whenever an if-else statement has a compound statement
	for either the if or else section, the statements of both
	the if and else sections should both be enclosed in braces
	(called fully bracketed syntax).

	if (expr) {
		statement;
	} else {
		statement;
		statement;
	}

	6.4. Braces are also essential in if-if-else sequences with no
	second else such as the following, which will be parsed
	incorrectly if the brace after (ex1) and its mate are
	omitted: 

	if (ex1) {
		if (ex2) {
			funca();
		}
	} else {
		funcb();
	}

	6.5. Do-while loops should always have braces around the body. 


7. Operators

	7.1. Uniary operators should not be separated from their
	single operand. Generally, all binay operators except
	. and -> should be separated from their operands by
	blanks or tabs.

	7.2. Some judgement is called for in the case of complex
	expressions, which may be clearer if the "inner" operators
	are not surrounded by spaces and the "outer" ones are.

	7.3. If you think an expression will be hard to read, consider
	breaking it across lines. Splitting at the lowest-precedence
	operator near the break is best. Expressions involving mixed
	operators should be parenthesized. Too many parentheses,
	however, can make a line harder to read because humans aren't
	good at parenthesis-matching.

	7.4. Terniary operators should be avoided.


8. Naming Conventions

	The following rules are to be applied on all new projects.

	8.1. Names with leading and trailing underscores are reserved
	for system purposes and should not be used for any
	user-created names. Most systems use them for names that the
	user should not have to know. If you must have your own
	private identifiers, begin them with a letter or two
	identifying the package to which they belong.

	8.2. Function names should be in lower case.

	8.3. Variable names that are created and used within the same
	file should be in lower case. However, variable names created
	globally by special configuration files should be in upper
	case.

	8.4. Avoid names that differ only in case, and also avoid
	names that differ only by underscores (like foobar and
	foo_bar).

	8.5. Avoid names that may be hard to spell or read. Be
	careful with 'l', '1', 'I', '0', 'O'.

	8.6. Avoid names that might conflict with standard library
	names.

	8.7. Don't be affraid of long names for variables or
	functions. It's better to have a long and understandable
	name than anagrams (clear_the_screen vs cls).


9. Special Considerations

	9.1. SQL

		9.1.1. ALWAYS double-check for SQL injection.

		9.1.2. Make the queries look clean. Use the heredoc
		sintax.

$query = mysql_query(<<<TEXT
	select		names
	from		users
	where		names like 'a%' and
			names like 'b%'
	order by	names
TEXT
);

		9.1.3. ALWAYS double-check for SQL injection.

		9.1.4. Set up the SQL user so that you have only the
		needed grants for each 'side' of the system: the
		Administration side can often select, update, insert
		and delete, while the User side can often only
		select information.

		9.1.5. ALWAYS double-check for SQL injection in ALL 
		forms, fields and querystrings.

		9.1.6. Check if insert/update/delete operations where
		done successfully, and notify the user.

		9.1.7. SQL is usually slow. Operations should better
		not be done on the SQL side. Use SQL only for
		storying data.

		9.1.8. SQL injection?

	9.2. ASP (Microsoft)

		9.2.1. Avoid using ASP for new projects. It's slow,
		bulky and expensive.

	9.3. JavaScript

		9.3.1. Don't use JavaScript as the only way to
		navigate through the site. Also, many effects can
		be achieved by CSS.

		9.3.2. The Internet Explorer has very different
		programming than the JavaScript Standards. Have the
		server define what kind of browser it is, and include
		the correct JavaScript while on the server.

		9.3.3. JavaScript should be always inside the HTML or
		included on the server side.

		9.3.4. If you think it's important to have comments,
		make them very short or only on the server side.
		There is no need to send comments to users.

		9.3.5. Choose the variable/object names wisely.
		They have to be short enough to make the page
		smaller, and long enough to be understandable.

	9.4. HTML/CSS

		9.4.1. Choose the object names wisely. They have to be
		short enough to make the page smaller, and long
		enough to be understandable.

		9.4.2. Don't rely on browser defaults: define either
		every formating option or none at all.

		9.4.3. Don't comment HTML/CSS coding. Or at least
		don't send these comments to the client.


10. Conclusion

	A set of standards has been presented for programming style.
	Among the most important points are: 

	10.1. The proper use of white space and comments so that the
	structure of the program is evident from the layout of the
	code. The use of simple expressions, statements, and
	functions so that they may be understood easily. 

	10.2. To keep in mind that you or someone else will likely be
	asked to modify code or make it run on a different machine
	sometime in the future. Craft code so that it is portable to
	obscure machines. Localize optimizations since they are often
	confusing and may be "pessimizations" on other machines. 

	10.3. Many style choices are arbitrary, based on a personal
	experience of 19 years of coding and the "Indian Hill
	Recommended C Style and Coding Standards" from Bell Labs.
	Having a style that is consistent (particularly with group
	standards) is more important than following absolute style
	rules. Mixing styles is worse than using any single bad style. 

	10.4. As with any standard, it must be followed if it is to
	be useful. If you have trouble following any of these
	standards don't just ignore them. Talk with your local guru,
	an experienced programmer or send me an e-mail
	(contato@fulviooliveira.com.br).





---------------------------------------------------------------------

Read more on Standards