SQR Programming Standards

What do compilers expect of the programs we create? Our programs should follow the syntax of the language and observe the practical limits of the compiler.

What do our customers and managers expect of the programs we create? Our programs should be created and available in a reasonable amount of time. Our programs should perform the operations described in the functional specification completely, accurately, and within a reasonable time. They should not have any undesirable side effects (e.g. don’t drop the database table while printing a report). They should be reliable (e.g. bugs should be rare).

What Are Standards?

Programming standards are traditions, guidelines, or rules that add more expectations about programs. They usually concern the appearance or style of the source code, something that does not matter to the compiler and the customer but does matter to anyone who maintains the code, especially someone who didn’t write it.

Standards can address various aspects of a program. There are cosmetic standards, which disappear in the compiled version of the program.

  • Program file names
  • Data file names
  • Usage of upper and lower case
  • Procedure names and order
  • Variable names
  • Horizontal and vertical spacing of code
  • Information to include in comments
  • Documentation of program changes

There are centralization standards, which encourage us to use common resources either to save development time, improve quality, or allow wholesale updates. For example, include files can contain frequently used code, directory paths for data files, constant values of substitution variables. (Constants can change. I use {num_emps} for create-array and load-lookup commands in many of my programs. I recently increased its value.)

There are functional standards that affect how the program works. Here are some examples:

  • When passing parameters to a procedure, list the input values first and the return values last.
  • When concatenating values in load-lookup or string commands, use tab (ASCII 9) as the delimiter.
  • Don’t nest control structures (evaluate, if, while) more than five levels.
  • Use date variables for dates.

I’m not sure how I feel about programming standards. We could argue that they add value to the code by making it more maintainable. We could argue that drain the art (or the fun) from programming. We could argue that some standards improve the code, other standards merely oppress the programmer, and standards in general miss the point. Ready? Let’s argue.

Standards Add Value

Standards usually emphasize neatness, meaning, and consistency. The goal is to make it easier to read and understand the code. This allows the author to return to his or her code years later, or a co-worker to help. If a program bug or some unanticipated condition stops a production process, time is money.

Standards Stifle Creativity

Do they? An English sonnet is a 14 line poem, in which each line has ten syllables and is written in iambic pentameter (every other syllable is emphasized). Shakespeare wrote 154 sonnets with the following pattern of rhymes: ABAB CDCD EFEF GG, and never complained that his creativity was stifled.

People who enforce standards can be annoying if they ignore the clever, efficient algorithms we invented and harp about the two blank lines between procedures that should have been three. Creativity will be stifled if we are so focused on the low level task of proper indenting that we cannot shift gears to use our language expertly. Shakespeare is not known for his spelling.

Standards Miss The Point

Here are several solutions to the same problem. Let’s assume that our program determines that $customer_code contains a single character – a lowercase, unaccented letter. All the code may be formatted properly, but not qualify as easy to maintain.

Here are excerpts from 103 lines of code. It won’t fit on the screen or a printed page. Its rhythm lulls us to sleep, easily overlooking a missing letter or a typo.

if $customer_code = 'a'
let $customer_code = 'A'
else
if $customer_code = 'b'
let $customer_code = 'B'
else

else
if $customer_code = 'z'
let $customer_code = 'Z'
end-if
end-if

end-if

This is better, because there are only 27 opportunities to mistype $customer_code rather than 52, and less chance of getting lost in the nesting.

evaluate $customer_code
when = 'a'
let $customer_code = 'A'
when = 'b'
let $customer_code = 'B'

when = 'z'
let $customer_code = 'Z'
end-evaluate

When I translate codes arbitrarily (a -> X, b -> N, etc.), I like to use string functions. However, I cannot endorse this solution, even if we think we know that $customer_code is a single, lower case letter of the alphabet. It’s still bulkier than the problem requires.

let $customer_code = substr('ABCDEFGHIJKLMNOPQRSTUVWXYZ', instr('abcdefghijklmnopqrstuvwxyz', $customer_code, 1), 1)

This is not much better.

let $customer_code = translate($customer_code, 'abcdefghijklmnopqrstuvwxyz', 'ABCDEFGHIJKLMNOPQRSTUVWXYZ')

This one is great if everyone has memorized the ASCII values of ‘a’ (97) and ‘A’ (65) – and if we’re working in ASCII.

let $customer_code = chr(ascii($customer_code) – 32)

Is there a way to write programming standards to guide us to this code? Can we write a programming standard that tells us to learn and use the built-in features of the language or the organization’s subroutine library?

uppercase $customer_code

The Impulse To Standards

I think that some managers, tired of sloppy code, start by asking people to “indent appropriately,” or to “add white space to group code into functional blocks.” This may be just too vague to work, so they find themselves writing and enforcing standards like this:

“In an evaluate block, the when conditions must be indented three spaces from the evaluate line and the commands under each when condition must be indented three spaces further. Any commands that extend past column 80 will wrap around to the next line, indented two more spaces. There will be a blank line, then a line of asterisks from column 2 to column 80 (preceded by an exclamation mark), then a blank line at the end of the code for each when condition. Any comments pertaining to a particular when condition will be under the when, not over it.”

Imagine a standard going on like that for twenty pages. Is it the frustration of long-suffering co-workers who couldn’t maintain each others’ code or was it overly fastidious devotion to tidiness?

A Happy Medium

If the goal is to improve the quality of our software and to achieve business efficiencies, let’s discuss that. A programming standard can seem to impose arbitrary rules chosen by the whim of the fussiest member of the organization. Alternately, it can evolve from a consensus of practitioners as to the best practices in the areas that matter. I am assuming a foundation of personal maturity, team spirit, and good will – actual results may vary according to the hiring and management practices of each organization. However, I believe that a minimal standard that the team values is better than a thorough standard that chafes.

Comments are closed.