Taken from issue 2 of our (new retired) email newsletter:
Be Predictable
Using a consistent coding style is "a good thing", but there are two instances where you should not necessarily impose your chosen style. Firstly, when you are modifying some existing code that uses a different style; and secondly, there will always be exceptional cases where you can justify a deviation.
In respect of the first instance, it is not desirable to leave a module with a mixture of styles in it, so you have the choice of either changing everything to your own chosen style, or of making your changes and matching the existing style. You need to make a judgement about the amount of work involved in changing the existing code - are you just making a small change (in which case, do it in the existing style), or are you making wholesale changes (in which case, convert the lot to your new style).
In the eventuality of an exceptional case where you believe it is necessary to deviate from the chosen coding standards (the second instance), make sure you understand the reason for the particular coding standard that you would wish to break. And if you feel you are truly justified in what you are doing, make sure you document what you have done and the reasons why you did it.
Comments
Comments are a crucial part of coding, in my opinion. There are some schools of thought that eschew comments (most notably the eXtreme Programming folks) but I don't wholly subscribe to any of those.
The subject of comments is a big one. In this issue I'll focus on comments related to DO blocks since I talked about DO blocks in the last issue.
In general, comments should inform. They serve very little purpose if they merely state things about the code that are already obvious to the casual observer. In addition to informing the reader about your intent and the reasons why you chose a particular coding solution, comments can be useful to aid with the layout and structure of coding.
The layout and structure of your code helps you and others to comprehend it. One common aspect of layout and structure is indentation. I'll discuss indentation in greater detail in a future issue, but suffice it to say that most programmers indent lines of their code to indicate blocks and sub-blocks of code. The indentation is a great help in displaying the structure and flow of the code. I use paired comments with DO blocks to add to this. See the example below:
if 1 eq 0 then
do; /* Never true */
moon = 'cheese';
clouds = 'marshmallow';
end; /* Never true */
The DO and the END statements share the same comment. In the simple example above they don't add much to the understanding, but in complicated code with lots of sub-setted IFs and plenty of ELSEs to go with them, being able to match an END with a DO easily has great value.
On a SELECT statement, I use them thus:
select (switch);
when (true)
do; /* true */
...
end; /* true */
...
end; /* select switch */
And with a DO loop, thus:
do ptr_digits = 1 to listlen(lDigits);
...
end; /* do over digits */
How about you? Do you do anything similar? Please leave a comment and let us know...