About the aim of coding style guides

Kai Hofmann <hofmann@hofmann-int.de>
31.12.2005

Table of Content

1.  Style guide background
2.  Typography and readability
2.1 About characters and words
2.2 About lines
2.3 About paragraphs
3.  Prevention of bugs
4.  Optimization
5.  Documentation
6.  Consistency
7.  Religion
8.  References


1. Style guide background

In [4] Ben Shneiderman defines in Chapter 4 "Command Languages"
the base goals of language design as follows:

- Precision
- Compactness
- Ease in writing and reading
- Speed in learning
- Simplicity to reduce errors
- Ease of retention over time

These points will also come into effect when talking about coding
style. But beside the design of a command language, the style of coding
within this language is a bit more. So we will define a coding style guide
as a mixture of the following points:

- Typography and readability
- Prevention of bugs
- Optimization
- Documentation
- Consistency


2. Typography and readability

One point (maybe the most important) of a coding style guide is about the formatting of
programm code. The formatting itself has a large influence on the readability of the
code itself. The base of readability is the typography [1,2,3,6]. Early roots of typography
goes back to the year 800 [7].
So when writing a coding style guide the experience from over 1200 years should be included.

For a programming language the following metaphors might work:

The whole story    : An application
A chapter          : A class
A subchapter       : A method/function
A paragraph        : A block of code
A sentence         : Small code that belongs together (like declaring some variables and calling a function with these variables as parameters)
A line             : A line
A word             : A keyword, or a variable name
A punctuation mark : A semicolon, parenthesis, square brackets, curly braces etc.
A character        : A character or mathematical symbol


2.1 About characters and words

During reading a line the space between words influences the readability [3, page 38].
Is the space between words to small, the words will flow into each other. This make it more
difficult to comprehend the text. Is the space between words to large it will disrupt the text
and interfere the readability.

For programm code this is the same. The following examples will show lines with
less/good/large usage of space:

Less space:
if(word!="value")then{break;}else{printf("word found!");}

Good space:
if (word != "value") then {break;} else {printf("word found!");}

Large space (set tab to 8):
if	(	word	!=	"value"	)	then	{	break;	}	else	{	printf	("word found!");	}


2.2 About lines

[2, page 42]
"The reader does not realize single letters. During normal
reading with an average tempo the eye makes a pendular movement,
comparable with the following of a ball on the tennis-court."

While reading line by line, the eye will move from the end of a line to the start of the next line.
When not starting the new line with the same indention, it will be harder for the eye to find the
start of the new line. The larger the indention difference is, the harder it is to continue reading.

For programm code the following examples will demonstrate the difference for none/good/large indention:

None indention:
if (word != "value") then
{
break;
}
else
{
printf("word found!");
}

Good indention:
if (word != "value") then
 {
  break;
 }
else
 {
  printf("word found!");
 }

Large indention (set tab to 8):
if (word != "value") then
{
        break;
}
else
{
        printf("word found!");
}

Also a wrong indention might result in a wrongly understanding of the code:

Wrong indention:
while (i < 10);
  if (word != "value") then
  break;
  else;
    printf("word found!");

Correct indention:
while (i < 10);
if (word != "value") then
  break;
else;
printf("word found!");


2.3 About paragraphs

[3, page 79] Paragraph partition
"Paragraphs are informational units and respectively completed thoughts, which collect one
or more sentences/statements. This units should not be to small or to large. Units that are
to large act like tapeworms and are very massive. They scare the reader and reduce the
unerstandability of the text."

For programming code the sentence "the code of a function should not be larger than one screen page"
covers this partly. Another part is to split up and document small blocks of code that belongs
together like declaring some variables, calling a function with these variables as parameters and
do something withe the result.

Without paragraph formatting:
a = 1;
b = 2;
c = 3;
result = dosomething(a,b,c);
printf("%d\n",result);
d = 4;
e = 5;
result = dosomethingother(d,e);
printf("%d\n",result);


Including paragraph formatting:

// Calculate a triangle
a = 1;
b = 2;
c = 3;
result = dosomething(a,b,c);
printf("%d\n",result);

// Calculate a rectangle
d = 4;
e = 5;
result = dosomethingother(d,e);
printf("%d\n",result);


3. Prevention of bugs

The prevention of (some) bugs lies also in the area of coding style guides,
because of the lack of consistence in the grammar of programming languages.
Example code:

for (i=0; i < 10; ++i)
  if (word != "value") then
    break;
  else
    printf("word found!");

When somebody else now detects a probelm within this code fragement
and wants to add some debugging code, he might write the following:

for (i=0; i < 10; ++i)
  printf("%d\n",i);
  if (word != "value") then
    break;
  else
    printf("word found!");

The code works not longer in a correct way, because the person who added the debug
code has forgotten to add the curly braces for the for block:

for (i=0; i < 10; ++i)
 {
  printf("%d\n",i);
  if (word != "value") then
   {
    break;
   }
  else
   {
    printf("word found!");
   }
 }

This kind of "adding a bug" often happens when a programmer wants to add debug code,
extensions etc. in a hurry. So it will be a good idea to write down in a coding style
guide to always use the curly braces for all kind of keywords that will have influence
on a block of code (like: for, while, if, else, switch, ...).

Another example for such a kind of bug is the usage of block comments (like /* ... */)
which can bring you into problems when you want to "comment out" a block of code,
because often these kind of block comments can not be nested:

for (i=0; i < 10; ++i)
 {
  printf("%d\n",i);
  /*
  if (word != "value") then
   {
    /* exit loop */
    break;
   }
  else
   {
    printf("word found!");
   }
  */
 }

In this example the outer comment have been added later for debugging, because it is not
allowed to nest these kind of comments, you will run into a syntax error after the "break;".
So it would be a good idea to use "line comments" (mostly created with '//') for the
"exit loop" comment.


4. Optimization

Optimization lies normally outside of a coding style guide, but as we can learn from
different sources there are also some small things that can have an influence on small
code optimizations.
For example there is a difference in using '' versus "" in PHP. Withing the "" you can
use a escape sequences as well as variables will be expanded. This will not happen
when using ''. So "" will take some more time by the PHP interpreter than ''.
Another more complex example is the usage of i++ versus ++i in programming languages
(See http://www.gotw.ca/gotw/ for more).
Because of compiler/interpreter internals the post incement version (i++) needs always
the creation of a temporary object, which will cost time and memory. To avoid this
++i should be used wherever possible.


5. Documentation

There are different ways and tools (like: CWEB, javadoc, phpdoc, doxygen etc.)
for writing inline documentation within program code. A style guide should define the
way and tool for writing this kind of inline api documentation.
Documentation does not only mean inline api documentation. There are also some
other points that will help someone in understanding what program code does:

* Naming of variables
* Comments on the end of line
* Line comments between small blocks of code (sentences)


6. Consistency

A coding style guide should ensure that the programm code is written in a
consistence way. For example the following code is not very consistent:

if (word!="value") then break;
else
 {
  printf("word found!");
 }

It would be more consistent when written in the following way:

if (word != "value") then
 {
  break;
 }
else
 {
  printf("word found!");
 }

Also a coding style guide should be consistent in itself. This means
that all examples in a style guide should follow the rules that the
guide defines by itself.


7. Religion

Writing a coding style guide is also some kind of religion, because there are often
"holly wars" about things like "using spaces versus tabs" or the way braces should
be placed like:

if (word != "value") then {
  break;
 }
else {
  printf("word found!");
 }

versus

if (word != "value") then
{
  break;
}
else
{
  printf("word found!");
}

or versus

if (word != "value") then
 {
  break;
 }
else
 {
  printf("word found!");
 }

As mentioned earlier there are often good reasons learned from typography, bugs or optimizations
that might help by making a decision for a style. Giving an explanation for a choice will also
help the reader to understand why a given style should be used.


8. References

[1] Ursache & Wirkung; ein typografischer Roman; Erik Spiekermann; 1986; Verlag Hermann Schmidt, Mainz
[2] Zeitungsgestatung; Typografie, Satz und Druck, Layout und Umbruch; Michael Meissner; 1992; List Journalistische Praxis
[3] Mut zur Typographie; Ein Kurs für DTP und Textverarbeitung; Jürgen Gulbins, Christine Kahrmann; 1992; Springer-Verlag
[4] Designing the User Interface; Strategies for Effective Human-Computer Interaction; Ben Shneiderman; Second Edition; 1992; Addison-Wesley
[5] Webanwendungen mit PHP 4.0 entwickeln; Tobias Ratschiller, Till Gerken; 2001; Addison-Wesley
[6] Typographie, Layout & Schrift Online; http://www.typo-info.de/
[7] Geschichte der Typografie; http://de.wikipedia.org/wiki/Geschichte_der_Typografie