December 7, 2005

A Coding Standards Wish List

A user on one of the online forums recently asked for suggestions for an SQR coding standards document. There wasn't much activity on the thread, but the answers generally fell into two categories. One group of people offered up their own standards documents as samples. The other group talked about the need for meaningful standards that address real objectives, as opposed to the usual "every variable name must begin with a capital letter" sort of thing.

This started me thinking about what I would consider to be essential coding standards. I wanted to come up with a very small list of points—sort of a "wish list" of things that I wished every SQR developer would do. (The following is written with SQR in mind, but it really could apply to just about any language.)

So here's my wish list. This is not a list of all the things we should be doing—I've written about a number of those things before. Instead, this is just the shortest list of really important points that I could think of. Maintaining SQR code would be so much more pleasant if everyone followed these "rules."

#1: Align and indent your code. It may seem a little surprising, but I think this is the single most important thing we can do to make our code understandable and maintainable. I find code that is scattered randomly around nearly impossible to follow. This extends to the SQL as well. (Remember that the only thing that must be aligned at the left margin in SQR is the list of fields/columns in a BEGIN-SELECT. Everything else, including the BEGIN-SELECT itself, can be aligned where it makes sense.) Align your code using spaces, not tabs. Different editors handle tabs in different ways.

Indent within statement blocks that alter the execution flow. For example, your IF, ELSE and END-IF should be aligned in the same column, and everything else within that block should be indented. BEGIN-SELECT, EVALUATE, and WHILE are other examples of these blocks. Don't indent to show logical groupings of statements. For example, if you have a DO statement followed by code that processes the results returned by the DO, don't indent those. Line them up instead. If you want to group statements logically, use blank lines or comments.

#2: Tag your changes. When maintaining existing code, don't delete or change code. Instead, comment out any unwanted code and add the new or changed code. On each line (both the commented-out and the new lines), add a comment that consists of the issue/ticket/case number:

  ! let #a = 1            ! 123
    let #a = 2            ! 123

In this example, the value of #a was originally set to 1. Issue 123 caused us to change this to 2. There is a lot of information here. We have the original code and can back out the change if needed. We can see what the real change was. By looking up the issue or ticket, we can determine when the change was made, by whom, and (importantly) why it was done. This helps in our understanding of the change and is critical if we need to maintain it.

One person on the forum said he prefers to rely on a version management system to highlight changes and allow rollbacks. This works, but if all you have is a list of versions without a tie back to the original issue, you are still left wondering why a change was made.

The most frequent objection to this seems to be that it will clutter your code. Well, after a change has "aged" for some time (say, a year), there's no harm in removing the comments.

#3: Comment your code. It's so easy to skip this step. When we're writing our code, its purpose seems so obvious. But even a few weeks later that same code may not be so clear, even to the person who wrote it.

Comments help our understanding, but don't rely exclusively on them. After all, the comment can be completely wrong and the program will still work correctly! Remember that elements such as procedure and variable names can also carry comment-like information.

    let $PlanType = '11'   ! Dental             Useful
    let $t = '11'          ! Set $t to '11'     Worthless

#4: Refactor your code. Many programmers stop immediately once a section of code works. Instead, I think that we should continue to improve our code (assuming that it's not a throw-away program to be run only once). "Refactoring" refers to improving and cleaning up code by removing duplication, simplifying, restructuring, deleting unused variables, and so forth. (Google it for lots of information.)

Until next time...