Coding standards

From DocForge

Coding standards are general rules by which programmers write good code. Each organization or team should come up with their own set of coding standards to help with readability, maintainability, and consistency among all of the developers.

There is no universal set of coding standards, but there are widely accepted best practices.

[edit] Indentation

Indent code consistently.

• All code at the same nested depth should have their lines begin with the same whitespace.
• Some developers prefer tab characters for indentation, while others prefer spaces. Modern text editors and IDEs often provide the option of soft tabs, which are a set of spaces the same width as a tab, or hard tabs, which are actual tab characters. Hard tabs offer the benefits of fewer characters and configurable widths, while spaces offer the benefits of consistency and better usability with some command line tools. The preference of tab types is subjective, but the choice should be consistent among a development team.
• Block delimiters, such as { and }, should always be placed consistently.

[edit] Naming

• Name variables in a short but descriptive manner. Each name should clearly state what it represents (e.g. user_name instead of my_var). Think noun when naming a variable.
• Name functions and methods based on the actions they perform. Think verb when naming functions.

[edit] Logic and Organization

• Avoid excessive shorthand code. While sometimes convenient, shorthand consisting of many statements can be difficult to decipher.
• In object oriented programming languages, it's often best to define each class in a separate source file.

[edit] Documentation

• Add comments for all code which isn't obviously comprehensible to anyone who will read it. Most code should be self-documenting, but often reading the thought process behind a segment of code will be helpful to anyone analyzing the code at a later time.
• For code used by multiple other systems, such as an API implementation, document functions, methods, and classes so other developers will not need to read the code to know what it does or how to call it.
• Use common code documentation conventions when they're available. Programs such as Doxygen, JavaDoc, and phpdoc can later read these comments and generate separate documentation.
• Write consistent file headers. Explain the reason the file exists or what it does. Add copyright information. Again, use a common convention so it's easy to parse.

[edit] Performance

Each programming language has various performance characteristics which favor one coding style over another. PHP, for example, has two string quotation styles, one of which causes embedded variable evaluation. It's therefore faster to use the quotation style that doesn't force variable evaluation when it's not necessary. Such style choices should be included in coding standards.

[edit] See Also

• Tips for new programmers