Rules With Most Significant Exceptions

Question

Every programmer is taught a basic set of rules for writing good, maintainable code early in their career. These include not using gotos, avoiding copying and pasting, avoiding globals, etc. However, sometimes rules that are only intended to be guidelines or rules of thumb get applied religiously by the more anal-retentive types, to the point where they harm maintainability, readability or performance.

What best-practice rule do you feel is a good idea in general, but is overzealously applied by programmers that fail to realize that rules have exceptions?

Answer 1

Hard to say...

Single return from a method: Nothing wrong with exiting early if a condition is met.

Answer 2

One exit point per function. I'm happy that I'm seeing more people use guard clauses to get out of functions early, but I still have a few co-workers who are adamant about one exit point per function.

Answer 3

Always use descriptive variable names. Great rule, but not particularly necessary if the variable in question is a simple loop index.

Answer 4

Here's another one: "Comment your code". Not if you do things like this:

// Loop over the array
for (int i = 0; i < n; ++i)
{
    x[i] = i;
} // end of loop over array

These kinds of useless comments make my blood boil. They're more heat than light, more clutter than insight. Make the code comment itself.

Answer 5

Look, the code has to do two things: express the program you want, and make itself clear to the reader who has to figure it out later. The rules are all there to help you do that. Read Orwell's six rules for writing sometime. The last one is "break all the other rules rather than do something outright barbarous." That's the real goal.

Answer 6

Use design patterns.

I have a quote, from whom I don't know, socked away on the "GoF Gone Wild" topic... "Look, kids, here's a factory-factory creating factory for creating factory-creators for creating factories for creating certain kinds of mud creatures!"

Answer 7

Don't use functional decomposition.

I use function decomposition when I have a small program that does one thing well. I also use it from the top level to tie my classes together. I use it at the lowest level to implement the methods of my classes.

Answer 8

Put everything in classes.

Not always; sometimes a good set of (static) functions will do what you want without the overhead of a class.

Answer 9

Echoing what duffymo said with an example from the current version of some source code (bare minimum changes to conceal the guilty):

/*
 =========================================================================


Function: int loadmsg (void)

    Inputs: void

    Outputs:

Returned Value:      FUNCSUCC or unknown message number

Purpose: loads text of all messages into menus, strings, and

Description:

    loadmsg() tests if message files can be found and accessed

Notes:

    Functions Called:
            loadstr()
    Called By:
            sys_startup()
    Constants Used:
    Global Variables Referenced:
            iFLAG
    Local Variables:
            cc      return value from rldinit

 ========================================================================
 */

static mint
loadmsg()

{
register mint cc;

if (cc = rldinit())
    return(cc);
return FUNCSUCC;
}

Indentation is accurate (that is, as in the actual code). How to deconstruct?

• The macro FUNCSUCC is 0.

• Consequently, the body of the function is equivalent to:

  return rldinit();

• The leading comments are almost all superfluous.

• The function loadstr() is not called - it doesn't exist.
• The variable iFLAG is not referenced.
• The inputs and outputs are immaterial.
• In fact, the whole function is called once - so the calling function may as well call rldinit() directly.
• This function is deleted in my working branch.
• This was 43 lines between the open comment and end of function - in place of a function call.

I wish it were an isolated instance. No, it isn't a file I work on primarily. It is, however, a file of just over 20,300 lines (and it isn't even the biggest maintained - as opposed to generated - source file in the system). No-one knows all of what's in it - and therefore no-one is responsible for spotting such problems. I do this sort of problem spotting rather consistently, but by accident when I have to look at the code.

(Another bugbear of mine: 900 of the 20,300 lines have trailing blanks on them. I hate that!)

Answer 10

I've always been annoyed by "give 'em what they want". Fair enough in theory, but in practice what they ask for is rarely what they want, it's more like the real problem half-solved in the first manner that popped into an untrained head. Deciphering desires from requests is an art in itself but it's a vital part of being a good programmer, IMHO (and at least doubly so in web-dev).

Answer 11

The single most overzealously-applied rule of thumb I've encountered is never using gotos.

In large applications, occasionally you'll run into a scenario, usually involving nested loops or control structures, where an outlying condition requires special processing. Programmers often use complicated control structures and flags and generally make the code a lot more elaborate than it needs to be rather than simply using a goto. Linus Torvalds made an argument for gotos that I think every serious programmer ought to take into consideration rather than blindly spouting off citations of Dijkstra's paper.

It's not that gotos are bad -- it's that like any programming tool, its mis-application can lead to headaches for yourself and other programmers down the line.