- Indent all blocks with tabs (ideally, set the tab width to no less than 4).
- Leave spaces between keywords and key characters, especially when doing
- calculations.
Group logical chunks of code within a block by placing them on consecutive
- lines, and leave a blank line between all others.
Separate blocks from each other using a blank line.
- Separate function headers and eventual function footers from the rest of the code
- using a blank line (importing globals is treated as a part of the function header).
Integrate block comments into the code, using the same indentation as the code
block to which each refers.
Put all line comments into the same column throughout a block.
To be able to understand text when reading, your brain must analyze the information
it receives from your eyes, identify the important parts, and then translate these parts
into correct order. Analysis is performed in two steps: physical analysis and logical
analysis. Physical analysis is performed first, by examining the visual structure of the
text; for example, paragraphs, rows, columns, and even spaces between words.This
process breaks up the perception of the text as a whole (for example, the sheet of
paper or the window on your desktop containing the text) into a tree-like structure of
smaller chunks. Assuming a top-down tree with the tree node at the top and leaves at
the bottom, the top of the tree contains the most generic information; for example,
the order of paragraphs that you have to read. At the bottom of the tree is something
like the order of words in a line, or even the order of characters in a word.
The logical analysis process takes this physical information, traverses the tree in order,
and tries to translate the information into a meaningful result.Whether this is a gram-
matical translation (what structure does the sentence have?) or a contextual translation
(what does the sentence mean?) doesn’t matter for this discussion; the important thing
is that the better the results of the physical analysis, the easier, faster, and better the
results of the logical analysis.
Logical analysis can compensate for missing information from physical analysis, but
only to a limited extent.
Asanexampletakethissentenceifyoucanreadityourlogicalanalyzerworksverywell.
You probably can read the preceding sentence, but it takes much longer and requires
much more concentration than the rest of the sentences in this blog. Important infor-
mation is missing (the spaces) for the first step in analysis, and you’re not used to that.
We could make it easier by adding a bit of punctuation:
Asanexample, takethissentence–ifyoucanreadit, yourlogicalanalyzerworksverywell.
The punctuation is useful information for your physical analyzer. Notice that it’s much
easier to read this version, as well as to refocus at any point of your choice. On to the
next step:
As an example, take this sentence–if you can read it, your logical analyzer
works very well.
This is the regular way you read a sentence, your native way of perceiving text. But we
could delineate the structure of the sentence even more:
As an example,
take this sentence–
if you can read it,
your logical analyzer
works very well.
This is an extreme method for using physical means to aid you in understanding the
sentence as quickly as possible. Note that the separation in this case hinders the natural
reading flow because you’re not used to seeing a sentence split up into syntactical
units—but for source code it’s an advantage. Because source code often contains com-
plicated constructs, formulas, and the like, it’s very important to support the reader by
giving the source a clear physical structure.This can be achieved by using indentation
and placing special keywords of your programming language at exposed positions.
Let’s take a look at a short PHP program:
<?function myfunc($myvar){$somevar=$myvar*2;return($somevar+1);}print myfunc(1);?>
The code itself is probably not an intellectual masterpiece, but let’s look only at its
structure.Without having read this snippet previously, would you be able to point
instantly to the start of the main code? Would you be able to mark the first and last
instruction of the function in it? Notice that even if you’re fast at finding the desired
places, your eyes will inevitably start at the beginning of the line, passing through the
source from left to right, stopping where you assume the target will be. Unconsciously,
your brain rereads the whole line because it’s missing information from the physical
analysis.To compensate for the lack of information from the first step, your logical
analyzer will take over this step as well and will be stressed twice as much. Just as with
a computer, your brain has limited power, so the additional workload for the logical
analyzer takes the form of a lack of capacity when your brain actually tries to under-
stand and memorize the source code. But understanding and memorizing is exactly
what you want people to achieve when reading your source code, and what you want
to do when reading other people’s sources.
So, this was almost a scientific approach to explain why formatting source code is
useful. Is there another reason? Oh, yes:Well-formatted source code just looks good.
Following are a few guidelines for what we think is the optimal style to use in
formatting source code. Please note that these are not mandated, but are regarded as
common style. Many industrial and Open Source projects have been formatted this
way, and it often pays to write in this style.
Put all block tags
(<?, ?>, <?php, <%, %>, {, }, etc.)
on separate lines.
It may seem somewhat excessive here, but imagine this code embedded into a few
thousand other lines of code, and you might change your opinion. Some people say
that the spaces between parentheses are more disturbing and irritating than helpful in
structuring the text—we must confess that sometimes that’s true.The examples in this
blog don’t always use this kind of formatting; we’re leaving the decision to you as to
whether to use this method.The most important thing is this: Be consistent. Once
you’ve decided to use a certain style, keep it at least throughout a project. If you’re
modifying other people’s sources, follow their style as well as you can. Consistency is
one of the most important aspects in professional development.
