Coding Guidelines
Contents
Coding Guidelines for Geeklog 1.4.
Geeklog 1.x never had any formal coding guidelines so you may find different styles in different places. As of March 2007, all new code in Geeklog will have to follow the PEAR coding standards (see below for details).
Why have Code Conventions?
To quote from the Geeklog 2 Coding Standards:
Code conventions are important to programmers for a number of reasons:
- 80% of the lifetime cost of apiece 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.
Why pick the PEAR coding standard?
Using the PEAR coding standard makes sense for several reasons:
- It's widely used and accepted in the PHP community.
- It's short and clear.
- Geeklog already uses some PEAR packages.
- Most of the code in Geeklog (apart from that based on lib-common.php) already uses a formatting style that's similar to the PEAR conventions.
PEAR Coding Standards
The following is about the actual source code formatting, i.e. how to place braces and what and how much whitespace to use. The PEAR naming conventions (file names, function names, etc.) are too different from Geeklog's and are not part of Geeklog's Coding Guidelines.
Specifically, we are adopting the following PEAR conventions:
- Indenting and Line Length (1)
- Control Structures (2)
- Function Calls (3)
- Function Definitions (4)
- Comments (5)
- Including Code (6)
- PHP Code Tags (7)
- File Formats (8)
To be defined: "Header Comment Blocks" (9). It may also make sense to adopt "E_STRICT-compatible code" (10) but that may be difficult to achieve in some contexts. It should certainly become a long-term goal, though.
