About Coding Style

Code Style

We have a very particular coding style that we believe unique enough to have to explain. Partly because of being dyslectic, the basic format style is so that the code can be easily read and understood — we call this:

Visual Clarity

Brace position and indent width and spaces before or after arguments and expressions, or all the rest of what most people call "programming style", actually has nothing to do with code being easily followed as one "reads" it.

No need to provide examples here — just look at our code. But let us offer a few reasons for our choices.

Line length is limited to 80 characters because we use a terminal and command line tools such as grep. This also helps reduce code complexity by the discipline of keeping expressions short and as simple as possible. Which brings us to this aphorism:

Simplicity is the cornerstone of good code.

Line length is short. Identifier names are short. Function names are short. Function length is short. File length is short. Statement block length is short. Indents are kept to a minimum.

This is all simply and only about clarity and about being able to quickly "see" what the code is doing. Not everybody uses an IDE or has a display that can show long lines. Long lines that are word-wrapped are hard to follow. And having to scroll the display left and right is bothersome.

We format the way we do simply because it makes it clearer to see what the code is doing. Which brings us to what we call our:

Five Minute Rule

We code with the idea that the code will be modified. Code is not poetry. Poetry gets written and stays the way it is. Code has the basic, innate property that it is to be modified — and modified often.

Comment Style

Our code commenting style has evolved over time and we have settled on a particular style that we think helps to understand the code — but in a unique way.

• Comments do not describe what the codes does but why the code is.
• Comments should be positioned to better highlight the code.

We use both /* */ and // style comments but in a particular way. We use the former for top-level code blocks (top of file, before or after functions, end of file), and the latter for code-right comments (for the most practical reason that we save three characters) and to introduce inside level code blocks.

We comment functions like this:

/* functionname - one line function description */

// one or two notes may occasionally go here like this
// perhaps explaining something not obvious

function functionname() {

        ...
}

We comment within functions mostly like this:

        Comments to the right				// always line up
        	 of code should be,			// like this to be
        		no matter what,			// more easily read
        			kept short		// and be to the point
 

so that code and comments have two distinct "columns", like so:

        +----------------------------------------------+----------------------+
        |  Code Goes Here                              | Comments Go Here     |
        +----------------------------------------------+----------------------+
 

We use the "breaking" of this rule as way to highlight something, like a change that is going to happen, by starting a comment at column zero:

        if (debug()) {

// I don't like this here! truncation needs to be moved into debug()

        	...
        }
 

And we sometimes start blocks with a "header" comment:

        // this does that weird thing

        if (isset($weird)) {
        	...
        }
 

(Note that the judicial use of a blank line can be just as important as a comment.)

Phpdoc Comments

Everybody, and we mean everybody, uses PHPDoc style comments. And nobody, and we mean nobody, supplies PHPDoc compiled source files. We have seen PHPDoc style compiled documentation and it may be nicely formatted HTML with links to functions and class and comments — but that's all it is. The documentation is simply a copy of the comments!

We're sorry, everybody, but that's useless and a waste of time. We won't do it.

Our documentation may not be much better right now, but we are working on fixing that.

Notes