Coding Standards

isber coding standards

this page is meant to specify a standard formatting of code. code standards are important in an organization like ours where several people may potentially need to make sense of others' code. these standards, more or less are based on those used by gnu.

these standards are more or less universal and ought to apply to all perl and php code. c code may have minor differences (e.g. comment style) but should maintain these guidelines as closely as possible.

commenting

there's a few comment types to deal with here: initial program description, section breaks, and line-by-line comments. the examples here apply to perl (# comments). for php, use the c++ style (//) in place of the (#) in these examples. for multiline and section breaks, use of the c style /* and */ in php.

initial program description - each program should start with it's name, cvs id tag ($Id$ after appropriate single line comment), a short description of what it does and how it's used, a usage section if appropriate, and a history section. this should be formatted as follows:

						#!/usr/bin/perl
	# $Id$
	##
	## get_account_info - get various imap account info from cyrus system. called 
	##                    remotely at user login and from myaccount info page
	##
	# USAGE:
	#  get_account_info <userid> 
	# HISTORY:
	#  20000207 m. dunham - created
	#  20001214 m. dunham - modified for cyrus
	#  20001219 m. dunham - included more quota details

section breaks - sections of code should be separated by a large comment block describing what the following code does. there ought to be two lines of whitespace before each section break and one after the section comment. format these like this:
```
						#---------------------
	# check arguments (perl)
	#---------------------
	code ... code ... code ...
	/*
	* determine when mail was last read (php)
	*
	*/
	code ... code ... code ...
	
```
each of the dash-lines must contain 20 - characters.

line-by-line comments - normal comments should be placed just above the code they refer to and justified inline with the code block:

						    # get the id of the most recently received message
	@most_recent_message_id_command = ( "/bin/ls -t $mailstore/*.", 
	"| /bin/cut -d/ -f7", "| /bin/head -1", "| /bin/cut -d. -f1");
	$most_recent_message_id=`@most_recent_message_id_command`;
	chop $most_recent_message_id;
	print "most_recent_message_id: $most_recent_message_id\n" if $debug;

whitespace

whitespace is your friend: it's difficult to overuse it. the following standards should be used as a minimum guideline:

always separate operators (e.g. =, <, >, =~, etc.) with whitespace on either side:
```
						if ($ARGV[0] =~ /([\-\w.]+)$/)
	{
	$userid = $1;
	}
	
```
use whitespace to line up blocks of declarations on the equals sign:
```
						$|     = 1;
	$debug = 0;
	
```
add a single whitespace between comment markers and the comment text:
```
						# check if the messages have been read or not
	
```
never use tabs! all code should be devoid of tab characters because of inconsistencies in the ways different editors handle tabs. all editors handle spaces correctly.

variable names

meaningful variable names are important. choose them wisely. quoting gnu: "The names of global variables and functions in a program serve as comments of a sort. So don't choose terse names--instead, look for names that give useful information about the meaning of the variable or function."

as for formatting, words in variable names should be lowercase and separated by underscores; don't use wordsthatruntogether or StudlyCaps. examples:

$numtmp = sprintf "%2.2d", $loginnum;                              # this makes little sense
$formatted_userid_instance = sprintf "%2.2d", $userid_instance;    # this is more clear

function names

meaningful function names are important. choose them wisely. function names should usually include a verb and a noun, for describing the action the function does, and what it does it to.

as for formatting, words in function names should be studlyCaps. dont' use lowercase and separated by underscores or wordsthatruntogether. functions should also have a commented name of the function after the closing brace. examples:

function incrementScore( int $score, int $increment )
{
$score+= $increment;
return $score;
} // incrementScore()

brace formatting

braces should be formatted using the "ALLMAN/BSD" style, named for the guy who wrote a buncha the original bsd-unix utiltities. this style looks like this:

if ("$last_seen_message_id" < "$most_recent_message_id")
{
$got_unread_mail = "yep";
}

this is the second-most-used method after kernighan and richie style, but imho it's much easer to read at the expense of more lines in your code.

all indents should be four (4) spaces: again, no tabs. you can configure most editors to insert four spaces in place of a tab - i recommend setting this up in your programming environment.

line length

no line should exceed 78 characters in length. if you have more code, continue it on the next line in alignment with preceding lines:

print "@mail_access_time:$got_unread_mail:" .
"$quota_percentage:$quota_limit:$quota_used\n";

converting old code

unformatted or misformatted code not can be run through perltidy to clean it up and (mostly) bring it up to spec. to generate code to these specifications, run perltidy as perltidy -bl -pt=2 -l78 <input_file> -o <output_file>

special thanks to matt dunham for writing the original version of this document

Institute for Social, Behavioral and Economic Research