Source Code Formatting
General Development Concepts
Discussion of the best practices for formatting your source code.
Date : 2006-02-10
Source Code Formatting
There are a couple of main reasons why source code formatting is a good idea and there are a couple of different schools of thought on how to go about it. I will try to look at each reason and each method with as little bias as possible.
First let’s talk about why we need to format our code. The main reason is to make the code easier to read. Source code formatting will have absolutely no affect on how the compiler or interpreter handles the code. For this reason the concept of source code formatting is often referred to as “Beautification”. Really the purpose is to make the code look nicer and be easier to read at a glance.
Anytime I try to tack down some basic rules for how this can be done I find nothing but disagreement. I’ve read articles that state that no spaces should be placed around the equal sign in variable assignments ie. (x=1). At the same time Microsoft states that the best practice is to use single spaces in all these cases ie. (x = x + 1). While it is difficult to state with any level of acceptance what the rules are for proper code formatting it is important to develop your own standard.
To develop your own standard will require answering a few questions. First, who else is going to see your code? Who is going to work with your code? Do you want to make the code readable (see article on Code Obfuscation)? What code editor are you using?
Knowing who is going to see your code will help you to determine the importance of formatting. Never assume that a client will not see your source code. Eventually they will see it. Clients will always be impressed by well formatted, clean looking code. Most of them have seen ugly code when it caused problems and all they learned is that ugly code causes problems. Programmers the world over could all cry out at once that compilers and interpreters do not know what the code looks like and non-programmers will still think that good looking code is better. So rather than try to educate the entire world of non-programmers get on the bandwagon and format your code.
Another reason to pay attention to your code formatting is for the programmers who will come after you. Maybe they will be making minor adjustments, maybe they will be fixing bugs (of course you didn’t leave a bug in your code… someone else must have added that code). Either way it will make their job much easier if your code formatting is clear and consistent. In this case it is also important to add in comments where necessary. Even comments can be made neat and orderly. Many programmers are in the habit of placing a comment block at the beginning of source code files that states the purpose of this code block, the author (with contact information), and a history of changes. These comment blocks can save many hours of guess work at a later time. Placing a comment block at the beginning of functions and procedures can also save time later when you’re trying to use a function and find that you can’t remember which variable is which. I’ve found huge code libraries that had several copies of functions all named slightly differently but with identical code because the programmers had lost track of which functions they already had so they wrote another one. Comments will help keep track of which functions you have in your libraries and how to use them.
In some cases programmers will want to hide their code from prying eyes. This article is not a discussion of open-source concepts so I will not get into reasons why we would or would not want to make our source code difficult to read. I would recommend searching for code beautifiers while searching for code obfuscators. Most of the work that is done by a code obfuscator can be reversed by a code beautifier. So ask yourself “Am I really making it take longer for someone to understand my code, or am I just making it take longer to deliver the code?”
The final question to help determine what kind of source code formatting you will use is “What code editor are you using?” This may seem unrelated but really many of the concepts involved in source code formatting come down to helping us see the most possible code clearly. On a standard screen with a standard text editor you have more horizontal space than vertical space. This layout would recommend that you conserve vertical space as much as possible by not adding in unnecessary blank lines. If you have placed a blank line there had better be a good reason for it. Some code editors, though, will add in toolboxes and directory listings that help us do our job but seriously bite into your horizontal useable area. In these cases it also becomes important to conserve horizontal space. The first recommendation that comes to mind would be to use 2 spaces rather than a TAB to indent logical areas. In environments where the horizontal area is severely limited it may help to limit these indentations to one character.
While we’re talking about our code editors let me mention that I firmly believe nobody should write code using a variable width font. They make code nearly impossible to read as well as making your indentation almost useless. So find a code editor that will let you change the font and set it to a fixed width font.
Although most of this discussion has been theoretical rather than practical I hope that understanding the reasons behind source code formatting will help you decide for yourself exactly how you want to do it. If I were to state the "Best Practice" for source code formatting it would have to be formatting your code in a clear and consistent manner that is in harmony with the use and purpose of your code.
Please share your methods of formatting and any pointers you have about where and how to best comment your code so we can all learn from each other.
No comments yet