About Coding Style
Code Style
The code has a very particular coding style that is 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 ClarityBrace 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 the code. But here are a few reasons for the 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:
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 RuleTab Stops
This is, perhaps, annoying to some. We use real tabs and pretend they are eight spaces. Real tabs reduce file size and eight spaces force us to keep indents to a minimum. That is all.
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 functions), and the latter for code-right comments (for the most practical reason that we save three characters) and sometimes 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 one:
if (debug()) {
// I don't like this here! truncation needs to be moved into debug()
...
}
Sometimes a block starts with a "header" comment:
// this does that weird thing
if (isset($weird)) {
...
}
The latest addition is using #
at column one to mark something that will change:
# this is too noisy
if ($music === TRUE) {
...
}
(Note that the judicial use of a blank line can be just as important as a comment.)