Style Guidelines Revisited

Coding style guidelines are great. They keep code looking consistent and can improve readability. As a result, many quality, widely-accepted coding styles exist – K&R, GNU, Whitesmith are a few examples – and are already loaded into IDE's such as Emacs or NetBeans. This makes me wonder: Why do certain universities insist on creating their own style guidelines?

I was recently reading through the "programming ground rules" of a course at a certain university, which will remain unnamed. For context, this course uses C++ as the main language for the course. While many of the guidelines are good ideas and common sense, I came across some interesting rules.

"Use the // comment style."

"Only use the /* */ comment style to temporarily comment out chunks of your program for testing and debugging." I must admit I was a little confused by this one. Comments compile out. Additionally, all the editors I know of are able to deal with both commenting styles. I just can't see how this affects readability.

Every function needs a doc banner. Even getters, setters, and the following function.

class Stack
{
public:
   // -----------------------------------
   // Returns true if the stack is empty.
   // -----------------------------------
   bool isEmpty() { /* . . . */ }
   // ...
};

Thankfully, a few rules from previous courses were noticeably absent. Arguments no longer must be labeled in a comment block as "in, out, or in/out". Do I have a problem with such labels? No, but when they are unnecessary they tend to reduce the readability of the comments. Take the following two functions for example. Yes, the function is deliberately simplified, but how much of your C++ code consists of such functions?

// isOutOfBounds( int x, int y)
// Returns true if the coordinates are in bounds.
// Returns false otherwise.
// ARGS: IN, IN
bool isOutOfBounds( int x, int y );

// Checks to see if the given coordinates are in bounds of the window.
// Note that x and y are expressed in screen coordinates.
bool isOutOfBounds( int x, int y );

The second declaration, though not rigidly formatted, provides far more information than the first. Also note the use of upper-case to convey that 1960's COBOL kind of feeling.

Also gone from the rules is the "30-line function limit", where points would be taken off for any function longer than 30 lines. While written to encourage modular design, the rule also encourages "code golf", where esoteric programming constructs and obscure evaluation rules help to fit the function inside of the line limit.

Take the following code snippets. Do they do the same thing?

void push( float obj_to_push )
{
   stack_data[current_index++] = obj_to_push;
}

// or

void push( float obj_to_push )
{
   current_index++;
   stack_data[current_index] = obj_to_push;
}

They do not do the same thing. The post-fix increment operator is evaluated after the assignment operator. Encouraging code golf with line limits encourages language constructs that, while clever and loved by language lawyers, are a pitfall for the creation of bugs.

Why then are programs graded according to criteria that at times are only tangentially related to good programming and at other times are actually opposed to proper coding? It would seem that the university system feels a need to conform programming into the standardized testing/grading paradigm currently embraced by many educational institutions, but has failed to quantify good programming practices.

How then, do we teach proper coding to students still struggling to master even the simplest aspects of programming such as language syntax? To be honest, I do not have an answer, and it would be preposterous if I purported to be qualified to propose proper pedagogical procedures. One thing I have noticed, however, is the inordinate amount of time spent learning language-specific constructs ( where the semi-colon goes ) in courses that advertise themselves as being about things such as "data structures".

Perhaps the way to go is to use a language with little syntax such as Scheme. Hal Abelson and Gerald Jay Sussman employed such a method in their book Structure and Interpretation of Computer Programs and their MIT course by the same name ( video lectures can be found here). Roughly one lecture covered the syntax of Scheme, rather than half of a semester using, say, Java ( as an aside, I would have to posit that Java's object reference system cannot be properly understood without first understanding the idea of pointers in a language such as C).

About