QB Knowledge Base > Technical Articles > Number 1

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.

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 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:

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

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

Originally posted on Sepent Technologies.