Coding conventions

Coding conventions are a set of guidelines for a specific programming language that recommend programming style, practices, and methods for each aspect of a program written in that language. These conventions usually cover file organization, indentation, comments, declarations, statements, white space, naming conventions, programming practices, programming principles, programming rules of thumb, architectural best practices, etc. These are guidelines for software structural quality. Software programmers are highly recommended to follow these guidelines to help improve the readability of their source code and make software maintenance easier. Coding conventions are only applicable to the human maintainers and peer reviewers of a software project. Conventions may be formalized in a documented set of rules that an entire team or company follows, or may be as informal as the habitual coding practices of an individual. Coding conventions are not enforced by compilers.

Software maintenance

Reducing the cost of software maintenance is the most often cited reason for following coding conventions. In their introduction to code conventions for the Java programming language, Sun Microsystems provides the following rationale:

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

• 40%–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.

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 an 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.

Coding standards

Where coding conventions have been specifically designed to produce high-quality code, and have then been formally adopted, they then become coding standards. Specific styles, irrespective of whether they are commonly adopted, do not automatically produce good quality code.

Reduction of complexity

Complexity is a factor going against security.

The management of complexity includes the following basic principle: minimize the amount of code written during the project development. This prevents unnecessary work which prevents unnecessary cost, both upfront and downstream. This is simply because if there is less code, it is less work not only to create the application, but also to maintain it.

Complexity is managed both at the design stage (how the project is architectured) and at the development stage (by having simpler code). If the coding is kept basic and simple then the complexity will be minimised. Very often this is keeping the coding as 'physical' as possible - coding in a manner that is very direct and not highly abstract. This produces optimal code that is easy to read and follow. Complexity can also be avoided simply by not using complicated tools for simple jobs.

The more complex the code is the more likely it is to be buggy, the more difficult the bugs are to find and the more likely there are to be hidden bugs.

Refactoring

Refactoring refers to a software maintenance 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 methods, 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.

Task automation

Coding conventions allow programmers to have simple scripts or programs whose job 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 specify 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 is to process existing software. Use of static code analysis has grown consistently since the 1950s. 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.

Language factors

All software practitioners must grapple with the problem of organizing and managing a large number of sometimes complex instructions. 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 shifted from purely procedural programming (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). 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. Tcl, which uses a brace syntax similar to Perl or C/C++ to delimit functions, 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 is 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. 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).

Common conventions

There are a large number of coding conventions; see Coding Style for numerous examples and discussion. Common coding conventions may cover the following areas:

• Comment conventions
• Indent style conventions
• Line length conventions
• Naming conventions
• Programming practices
• Programming principles
• Programming style conventions

Coding standards include the CERT C Coding Standard, MISRA C, High Integrity C++, see list below.

See also

• Comparison of programming languages (syntax)
• Hungarian Notation
• Indent style
• List of tools for static code analysis
• List of software development philosophies
• MISRA
• Programming style
• Software metrics
• Software quality
• The Power of 10 Rules

List of coding standards

Coding conventions for languages

• ActionScript: Flex SDK coding conventions and best practices
• Ada: Ada 95 Quality and Style Guide: Guidelines for Professional Programmers
• Ada: Guide for the use of the Ada programming language in high integrity systems (ISO/IEC TR 15942:2000)
• Ada: NASA Flight Software Branch — Ada Coding Standard
• Ada: ESA Ada Coding Standard - BSSC(98)3 Issue 1 October 1998
• Ada: European Space Agency's Software engineering and standardisation
• C: CERT C Coding Standard CERT C Coding Standard (SEI)
• C: Embedded C Coding Standard (Barr Group)
• C: Firmware Development Standard (Jack Ganssle)
• C: MISRA C
• C: TIOBE C Standard
• C++: C++ Core Guidelines (Bjarne Stroustrup, Herb Sutter)
• C++: Quantum Leaps C/C++ Coding Standard
• C++: C++ Programming/Programming Languages/C++/Code/Style Conventions
• C++: GeoSoft's C++ Programming Style Guidelines
• C++: Google's C++ Style Guide
• C++: High Integrity C++
• C++: MISRA C++
• C++: Philips Healthcare C++ Coding Standard
• C/C++: C/C++ Coding Guidelines from devolo
• C#: C# Coding Conventions (C# Programming Guide)
• C#: Design Guidelines for Developing Class Libraries
• C#: Brad Abrams
• C#: Philips Healthcare or Philips Healthcare C# Coding Standard
• D: The D Style
• Dart: The Dart Style Guide
• Erlang: Erlang Programming Rules and Conventions
• Flex: Code conventions for the Flex SDK
• Java: Ambysoft's Coding Standards for Java
• Java: Code Conventions for the Java Programming Language (Not actively maintained. Latest version: 1999-APR-20.)
• Java: GeoSoft's Java Programming Style Guidelines
• Java: Template:Dmoz
• Java: TIOBE Java Standard
• Java: SoftwareMonkey's coding conventions for Java and other brace-syntax languages
• JavaScript: Code Conventions for the JavaScript Programming Language
• Lisp: Riastradh's Lisp Style Rules
• MATLAB: Neurobat Coding Conventions for MATLAB
• Object Pascal: Object Pascal Style Guide
• Perl: Perl Style Guide
• PHP::PEAR: PHP::PEAR Coding Standards
• PHP::FIG: PHP Framework Interop Group
• PL/I: PL/I Style Guide
• Python: Style Guide for Python Code
• Ruby: The Unofficial Ruby Usage Guide
• Ruby: GitHub Ruby style guide
• Shell: Google's Shell Style Guide

Coding conventions for projects

• Apache Developers' C Language Style Guide
• Drupal PHP Coding Standards
• GNU Coding Standards
• "GNAT Coding Style: A Guide for GNAT Developers". GCC online documentation. Free Software Foundation. Retrieved 2009-01-19. (PDF)
• Linux Kernel Coding Style (or Documentation/CodingStyle in the Linux Kernel source tree)
• Mozilla Coding Style Guide
• Mono: Programming style for Mono
• OpenBSD Kernel source file style guide (KNF)
• Road Intranet's C++ Guidelines
• Style guides for Google-originated open-source projects
• The NetBSD source code style guide (formerly known as the BSD Kernel Normal Form)
• Zend Framework Coding Standards
• ZeroMQ C Language Style for Scalability (CLASS)