Writing Understandable Code

It is always a challenge to write robust, quick and optimized code while keeping it structured enough to be readable by you and others later. In future articles we will discuss how to write optimized code. But now, how should you write a piece of code that you can understand it later. Have you ever written a piece of code that you couldn't understand how it works later? In this article we will go through concepts of writing structured code.

Naming
Choosing suitable names for the elements of your code can make it a lot more understandable. Names should exactly tell what the element is. For a function or procedure, start the name with a verb, as in "GetFreeSpace". For variables, the name should tell what it contains, as in "FreeDiskSpace". You may also want to add a type prefix such as "n" or "int" for integer variables like "nArrayIndex", but this is not always needed –some programmers find it useful and some not. Notice the use of capital letters in the examples gives. Capitalizing the first letter of each word in the name can make it more readable. Avoid using one letter for variable names except for loop indexes.

Named Constants
Use named constants instead of literal values. For example, instead of writing "For i = 1 to 10" you may write "For i = 1 to RowsCount". Using named constants has two main advantages. First, it is easier to understand what the value represents. Second, further changes to the code will become easier.

Comments
Comments are what most programmers leave for the future and that's the mistake, because they won't do it! Always add comments while you are coding. Describe everything in your code. The following rules can help you:

• Add comments before or next to the variables declarations and describe what they are and/or how they are used in the code.
• Add comments before every block to describe what it is for.
• Comment tricky parts of the code. This is very important, because usually you use some coding tricks to make the code better and faster, but later you won't understand how it works.
• Write a comment block at the beginning of every procedure, describe its inputs and outputs, what it does, and/or how it works. Don't go into details of the routine, however –they should be described inside the procedure.
• Some programmers like to have a history of their work. They may want to add a comment block at the beginning of the procedures and modules. This block contains information such as date of last update, bug-fixes, etc.

Format
Properly formatting the code also makes the code better to understand. Some common ways of proper formatting are:

• Indent nested blocks. This is really necessary to recognize nested blocks from each other. For example, if you have three nested FOR loops with four IF blocks inside them, without indenting the code you will easily mix up with the blocks.
• Paragraph your code. Keep related lines together and leave a space between two paragraphs of related code. If you haven't done such thing in your code, just try it. Then you will see how greatly your code becomes a lot more understandable with this little advice.
• Declare all the variables at the beginning of the module or procedure. This makes finding the declaration of each variable easy. (You don't declare the variables? That's a big mistake. Not declaring the variables makes your code both less optimized and not structured.)

Conclusion
This article was a little help towards structured coding. But you, yourself, should choose the way you code. Maintain a standard for yourself. If you have a standard personal way of coding, you will find your code more understandable for yourself. In this article we only discussed the structure of the code. In later articles, we will discuss some coding techniques which will also make your code more understandable. For the last words, keep a balance between structured coding and optimized coding. Good code should have both specifications.

By: Homayoon.P.A.
November 10, 2002