A Simple Style Guide for Programmers

Writing a program is not a private conversation between you and your computer, it is to be read by people ... you, your coworkers, the people who will maintain it, the people who replace you, etc. Here are some of the most basic stylist rules used by professionals:

  1. Indent at least 3 spaces but not more than 8. This is enough to stand out but not so much that code shifts wildly across the page.

  2. If your indenting is over 4 levels deep then make the deeply indented code a procedure.

  3. Use blank lines between groups of lines of code that have a common purpose. In every 10 or so lines of code there should be at least one blank line form paragraphs of code. You would never write a book without paragraphs, same for your code. Consider commenting in an single line of informative text before each paragraph.

  4. Use at least two blank lines before a procedure so that the procedures stand out.

  5. Put a comment block before every procedure even if it is only a couple of lines.

  6. Always put a space after a comma. This makes lists much more readable.

  7. Never write a procedure that is more than a page long.

  8. If procedure calls are of the form procname(args) then there should be no space between the procname and the opening paren.

  9. If there is a keyword followed by an opening paren allowed in the language then there should be a space between the keyword and the paren as in: while (

  10. In C try to hide opening braces and expose closing braces.
    	if (test(y)) {
    	    stmt1;
    	    stmt2;
    	}
    

  11. else should begin a line. Never use the "elephant ears else":
            if (test) {
                dogs();
                cats();
            } else {         // BAD elephant ears else
                bats();
                ants();
            }
    
    but rather:
            if (test) {
                dogs();
                cats();
            } 
            else {         // OK
                bats();
                ants();
            }
    
    this makes the location of the else clear.

  12. An opening brace should always be preceeded by a blank.

  13. If you have a single statement after an if or looping construct and you don't provide a separate block for it (such as using braces in C++) then put the single line right after the if. Not:
     
    	if (test) 
    	    x = func(y);
    
    but rather clearly attach the code to the if or use braces:
     
    	if (test) x = func(y);
    
    or
     
    	if (test) {          
    	    x = func(y);
            }
    
    You may violate this rule when one of the if clauses (then or else) has a block in braces then both should have a block in braces. Not:
            if (test) x = func(y);
            else {
                cat();
                dog();
            }
    
    but rather:
            if (test) {
                x = func(y);
            }
            else {
                cat();
                dog();
            }
    

  14. Use meaningful variable names. Trivial counters, indexs in for loops, and temporaries can optionally be single letters but the rest should have meaning. Bad variable names include things like var, thx1138, blah, and stuff. Consider using "camel case" (mixed upper and lowercase) to make readable variables: windVelocity or carsPerSecond. Use simple variables such as x or v if the well known or reference math equations use those specific variable names.

  15. Avoid mixing declarations and executable code in the middle of blocks. Move declarations to the beginning of enclosing blocks when possible. If this moves the declarations away from the scope of use then create a block specifically for defining the scope of the declarations. This makes the scope clear and the operations on the variables uncluttered. (This is an often contested view and some object operations require mixing of declarations and operations. But decluttering the opertions with declarations I find refreshing. You can make your own choice.)

  16. Whenever possible, initialize variables that are used in a loop right before the loop. Separation of initialization of variables and use of variables in a loop could be a source of future bugs and makes the code less readable.

  17. Avoid just pasting duplicate code around in a program, when a procedure can be created and duplicate code removed. Only do this if it is logical.

  18. Apply these rules consistently throughout your program. You lead a reader into your style. Don't change it on them midstream.

  19. Do not surprise the user with unexpected "cleverness", when you can make your code say clearly what it is doing. This kind of cleverness often leads to "clever" and hard to find bugs.