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