CODE_COMMENTS - index

Code Comments

Our code commenting style is evolving. Here we explain what we do.

First, we have two basic requirements for a code comment. A comment:

1. Should not describe what the codes does but why the code is.
2. Should be positioned to better highlight the code.

Second, we do not like, therefore do not use, PhpDoc style commenting — more on why later.

We switch between /* */ and // style comments often, but generally, 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! eg. "// do this here" vs. "/* do this here */", which gives us more room to type right up the the end of the line, which is column 79).

We think block comments should be lengthy and should be word-wrapped, using a block comment style of /* */.

/*
When writing a comment we start at the beginning of the line with no indenting, 
and we do not line break. This way we can quickly get our thoughts down without 
having to take the time to break each line or to have to enter spaces. Just 
like when you are writing documentation!

When done with the comment we then we go back and put in the newlines. This is 
so that when you read our long comments we can rest assured that no matter your 
editor's tab or word-wrap settings you will see the comment in all it's glory, 
neatly lined up!
*/

// But sometimes it is not big deal to just dash off a few lines
// like this.

We comment functions like this:

/* functionname - one line function description */

// one or two notes may occasionally go here like this

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)) {
        	...
        }

 

This is what we are calling, Making code a Visual Experience.

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