| A Coding Standards Wish List | KEVIN RESCHENBERG
12-07-2005 |
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.)
|
