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.
Contents |
[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.
- Choose CamelCase or underscores for naming and use it consistently. For example, a team may choose to name all functions in CamelCase with the first letter lower case (e.g. moveItem). What's important is that one naming style is chosen and used consistently.
[edit] Logic and Organization
- Avoid excessive shorthand code. While sometimes convenient, shorthand consisting of many statements can be difficult to decipher. When using not-so-obvious shortcuts, be sure to use code comments to explain to others, and even yourself, what it's meant to do.
- In object oriented programming languages, it's often best to define each class in a separate source file.
- Organize code and files in line with the application's modularity. For example, the administrative section of a web site can have its scripts and other files in one directory while the public side of the site is in another.
[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 sometimes 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.
