A.2. Style Guide

A.2.1. Coding Style

Solar classes adhere to the PEAR coding standards, with one minor deviation. In PEAR, only private elements have an underscore prefix; in Solar, both private and protected elements have an underscore prefix.

public    $public;
protected $_protected; // in PEAR, this would be $protected instead
private   $_private;

A.2.2. Problem-Solving Style

In every Solar class, we strive for simple, easy-to-test, and easy-to-explain solutions. We like fast execution, but prefer to err on the side of slower-but-simpler instead of faster-but-obtuse.

When obtuse or complex code is unavoidable, it is thoroughly commented and outlined with inline narrative comments as a teaching exercise. We know that some poor guy is going to have to figure out how the code works, so we take a little extra time and comment so that others can comprehend what's going on.

A.2.3. Namespaces

Currently, Solar uses the PEAR-style pseudo-namespaces that existed before PHP 5.3 (i.e., using a vendor prefix on each class). This does not prevent the use of namespaces in your own Solar-based code. Future versions of Solar might use PHP 5.3 formal namespaces.

A.2.4. Inline Documentation Style

Solar uses PHP Documentor documentation blocks for every class, property, and method. This makes it easy to auto-generate class documentation using the Solar make-docs command-line tool.

All inline documentation uses Solar wiki-style markup so that the generated class documentation is automatically linked and styled.