In my last article I discussed how you can improve your application by using the multi-tier architectural design pattern. Now, I will talk about how you can give yourself some sanity by following standards intended to be used when programming in your favourite language. No, really!
Very often in chatrooms dedicated to programming, such as the one provided by GameDev.net (amongst a plethora of others), people will paste their problem as a code snippet. Almost always, the code is a disorganized heap of garbage. It is hard enough having to find the problem, but don’t make things harder on yourself and on those trying to help you by leaving your work looking like a mess. Follow a clean, consistent coding style.
If you are unable to read your own source files, do you think someone else will do it for you?
That question is no joke. Neatly written text is much nicer to look at than something that was written sloppy and without a care for the reader. Remember: programming languages exist for humans to read and understand easier, not for machines. The least you can do for yourself is follow a few basic guidelines, such as the ones I’m about to present:
- Be consistent
- Use whitespace wisely
- Write interfaces as if the person would guess what names methods have
- Divide code up into logical modules, using descriptive file, class, and variable names
1. Be consistent
Consistency is one of the best things you can do when it comes to finding a coding style. It lets the reader adapt quickly to the way your code is organized, and removes confusion when the person is reading each method. Without it, they will jump around trying to read the code, not even begin to understand it, because the code does not follow a uniform style.
Best way to be consistent is to find a naming pattern and a spatial pattern for each of the typical concepts found in programming languages: classes, methods, local variables and comments. A spatial pattern may be the number of blank lines between each method, followed by the comments of the next method. Within the comments can be the purpose of the method, the expected input, and the guaranteed output (Aside: Look into Design-By-Contract). Repeating this for each method will put the user in a mindset where they can find information quickly because they know where to look — you’ve been consistent with your code.
Often times when working in a team setting, the coding style will be decided upfront at the beginning of the project. When it isn’t, and you are modifying someone else’s source files, try to find a pattern them and conform to the convention it has to make your modifications seem as if one person wrote everything. This decreases the times a person has to pause and go back to re-read a block of code, as if it stands out unnaturally.
2. Use whitespace wisely
It’s easier for us to pick apart information by logically grouping them. Just like this website, and many forms of media, whitespace is the cruicial component in grouping data that belongs together. Misusing whitespace, or omitting blank lines or spaces at all, can result in the reader having to strain their eyes and read several times carefully to understand something very basic. Take for example this code snippet:
int blah;
cin >> blah;
int tmp = 1, tmp2 = 0, tmp3;
for(int i=1; i < blah; i++ )
{cout << tmp2 << ", ";}
Seeing code like this everywhere can quickly turn into a nightmare for the reader. Omitting the obvious flaws with asking for user input without sanitizing, there is practically zero whitespace, leading the person to read otherwise useless syntax like the parentheses and brackets. One possible solution is as follows:
int tmp = 1, tmp2 = 0, tmp3;
int blah;
cin >> blah;
for(int i = 1; i < blah; i++)
{
cout << tmp2 << ", ";
}
Following a logical whitespace trend lets the user read less gibberish, and focuses more on the code that matters, because it spatially groups the important parts together.
3. Write interfaces as if the person would guess what names methods have
Every now and then I find myself trapped a discussion regarding how bad the Win32 API is. These kinds of statements could not be further from the truth. One of the things that the Win32 API particularly excels at is it’s naming convention. A lot of the time, it’s possible to not only think of a function that should exist, but to get the name of the function correct, under three tries. This kind of naming convention is a must for any serious developer, because putting in a little thought into symmetric naming of starting/stopping functions such as BeginPaint and EndPaint can go a long way in making it as least difficult as possible for the user of your code.
4. Divide code up into logical modules, using descriptive file, class, and variable names
Again, another seemingly obvious thing to say, that is often overlooked completely or unknown entirely. Grouping together methods that share logic in common makes it a lot easier to get the big picture regarding all those methods by simply reading their names. Sometimes, I find myself figuring out how something is implemented just by reading the name of the class, or method, or a particular comment that gives away subtle hints or flaws with the implementation. This is golden because it brings us one step closer to understanding a lot of code just by taking the time to give the variables some meaning. Using the previous example as a guideline, lets fix it up so it’s a little more descriptive in it’s functionality:
static const int PrintedValue = 0;
int repeatValueCount;
cin >> repeatValueCount;
for(int i = 1; i < repeatValueCount; i++)
{
cout << PrintedValue << ", ";
}
Through variable naming alone, we can deduct the purpose of the algorithm. This is one of the things a serious programmer should be striving to achieve, a self-describing naming convention.
A coding convention is more than just pretty text
Eventually, if the coding convention is kept consistent throughout the project, we will have little guesswork to do as to where things are located, because it will become apparent through patterns found in the programmer’s choice of placement. As soon as we figure out the programmer’s style, we have an easier time traversing code and figuring out what it does. We can only do this if the programmer in question (that is, you) has taken the time to organize everything in a logical, thorough manner.
Recommendations on available Coding Styles
For users of C#, reading the C# Coding Style Guide is a must. I highly recommend downloading the Philips Medical System Coding Standards (PDF) as they conform to the standards laid down by Microsoft, and are ubiquitous. This same convention can be used for C++.
For users of C, the Indian Hill Style and Coding Standards is the most widely known coding standard, and is geared towards readability and removal of confusion.
Last but not least, internal conventions of a language
One last thing that is essential to follow is the conventions of a specific language or framework. By abiding by the standards of the language, you remove the reader’s confusion and make your code easier to scan through. An example would be:
If a C++ object has to manage it’s own memory, the copy constructor, assignment operator, and the destructor should be implemented by the programmer to prevent bugs or memory leaks.
Now, if a typical reader such as me stumbles upon your class header file and sees that you are overloading these, I will take note and look for dynamic memory in the implementation file. If the methods end up being empty, the convention is broken and nothing is gained.
C# has it’s own conventions, a popular one being Overloading Equals() and Operator==.
Conclusion
By following a set standard of rules and conventions given a programming language, framework, or environment, you will reduce confusion of the reader, and in turn they will be able to read your code and get the bigger picture quicker than usual. As an added bonus, returning to old code after months or years will not be as difficult as it would be if no standard at all was followed.
So make it easy for others to help you when you have a problem you can’t solve: don’t make reading simple code difficult!
Comments