Coding conventions

From Wikipedia, the free encyclopedia

Please help improve this article or section by expanding it.
Further information might be found on the talk page or at requests for expansion.
This article has been tagged since January 2007.

Coding conventions are rules that computer programmers follow to ensure that their source code is easy to read and maintain. Software source code is plain ASCII text. Coding conventions are important only to the human maintainers and peer reviewers of a software project. Conventions may be formalized in a documented standard an entire team or company follows, or may be as informal as the habitual coding practices of an individual. Conventions and standards have no impact on the executable programs which are created from the text source. They may, however, make software tool development easier.

Consistently formatted source code simplifies future tool development in cases when the tool depends on the static structure of the source.

1 Software maintenance
- 1.1 Quality
- 1.2 Refactoring
2 Task automation
3 Language factors
4 Common conventions
5 References
6 See also

[edit] Software maintenance

Software maintenance is the most often cited reason for coding conventions. In their introduction to code conventions for the Java Programming Language, Sun Microsystems provides the following rationale:^[1]

Code conventions are important to programmers for a number of reasons:

80% of the lifetime cost of a piece of software goes to maintenance.

Hardly any software is maintained for its whole life by the original author.

Code conventions improve the readability of the software, allowing engineers to understand new code more quickly and thoroughly.

If you ship your source code as a product, you need to make sure it is as well packaged and clean as any other product you create.

[edit] Quality

Software peer review frequently involves reading source code. This type of peer review is primarily a defect detection activity. By definition, only the original author of a piece of code has read the source file before the code is submitted for review. Code that is written using consistent guidelines is easier for other reviewers to understand and assimilate, improving the efficacy of the defect detection process.

Even for the original author, consistently coded software eases maintainability. There is no guarantee that in individual will remember the precise rationale for why a particular piece of code was written in a certain way long after the code was originally written. Coding conventions can help. Consistent use of whitespace improves readability and reduces the time it takes to understand the software.

[edit] Refactoring

Refactoring refers to a software maintanance activity where source code is modified to improve readability or improve its structure. Software is often refactored to bring it into conformance with a team's stated coding standards after its initial release. Any change that does not alter the behavior of the software can be considered refactoring. Common refactoring activities are changing variable names, renaming, moving methods or whole classes and breaking large methods (or functions) into smaller ones.

Agile software development methodologies plan for regular (or even continuous) refactoring making it an integral part of the team software development process.^[2]

[edit] Task automation

Coding conventions make it possible to write simple scripts or programs whose job it is to process source code for some purpose other than compiling it into an executable. It is common practice to count the software size (Source lines of code) to track current project progress or establish a baseline for future project estimates.

Consistent coding standards can, in turn, make the measurements more consistent. Special tags within source code comments are often used to process documentation, two notable examples are javadoc and doxygen. The tools specifies the use of a set of tags, but their use within a project is determined by convention.

Coding conventions simplify writing new software whose job it is to process existing software. Use of static code analysis has grown consistently since the 1950's. Some of the growth of this class of development tools stems from increased maturity and sophistication of the practitioners themselves (and the modern focus on safety and security), but also from the nature of the languages themselves.

[edit] Language factors

All software practitioners must grapple with the problems of organizing and managing very many detailed instructions, each of which will eventually be processed in order to perform the task for which it was written. For all but the smallest software projects, source code (instructions) are partitioned into separate files and frequently among many directories. It was natural for programmers to collect closely related functions (behaviors) in the same file and to collect related files into directories. As software development evolved from the purely functional constructs (such as found in FORTRAN) towards more object-oriented constructs (such as found in C++), it became the practice to write the code for a single (public) class in a single file (the 'one class per file' convention).^[3]^[4] Java has gone one step further - the java compiler returns an error if it finds more than one public class per file.

A convention in one language may be a requirement in another. Language conventions also affect individual source files. Each compiler (or interpreter) used to process source code is unique. The rules a compiler applies to the source creates implicit standards. For example, Python code is much more consistently indented than, say Perl, because whitespace (indentation) is actually significant to the interpreter. Python does not use the brace syntax Perl uses to delimit functions. Changes in indentation serve as the delimiters.^[5]^[6] Tcl, which does use a brace syntax similar to Perl or C/C++ to delimit functions, it does not allow the following, which seems fairly reasonable to a C programmer:

set i 0
while {$i < 10} 
{
   puts "$i squared = [expr $i*$i]"
   incr i
}

The reason being that in Tcl, curly braces are not used only to delimit functions as in C++ or Java. More generally, curly braces are used to group words together into a single argument.^[7]^[8] In Tcl, the word while takes two arguments, a condition and an action. In the example above, while is missing its second argument, its action (because the Tcl also uses the newline character to delimit the end of a command).

[edit] Common conventions

Naming conventions
- Classes should be nouns and begin with a uppercase letter.
- Methods should begin with a verb and a lowercase letter.
- All constants should be ALL UPPERCASE
One class per file
An extra character early in a comment block to delimit the beginning of externally published or processed documentation.