Letter the Seventh – The Curse of Comments

24Jun11

My Dear Malware,

It has recently occurred to me that I may, in my advice to you, perhaps have concentrated on the purely technical side of the tempter’s trade – after all, most of our patients are quite capable of of misusing thinks like constructors, references and namespaces without any assistance or prompting from us! I would like to focus your attention on some of the less abstruse ways of bedevilling a programmer. For example, have you considered the many possibilities of the misuse of comments in code?

Of course, the best and easiest way to lead a human astray is to suggest that he or she does not really need to do something. If you can get them to omit comments altogether, because their code is “self-documenting” (oh, what a happy day in Hell it was when our marketing department thought up that one!) then you are home and dry. Unfortunately, certain dratted humans have a horrible tendency to read books on “best practices” (another one of ours, incidentally) which suggest at least a few comments are required. If you are dealing with one of these miscreants, I suggest you take the following approach.

Firstly, suggest to them that every source file should contain the full text of whatever license they are using. This has two wonderful effects:

  • Anyone reading the file will have lost the will to live long before they get to the actual code.
  • When the license needs to change, as it almost certainly will, every single file in the project will have to be edited!

You should of course do your utmost to conceal the fact that a simple copyright string, and a copy of the license in the root directory of the project are all that is actually required.

Secondly, you should arrange that the “coding standards” (wonderful things, I will have more to say about them in a later letter) for the project should insist that every function should have a header that looks like this:

///////////////////////////////////////////////////////////////////////////////////
// Function name:
// Purpose:
// Preconditions:
// Postconditions:
// Parameter 1:
// Parameter 2:
// etc.
// Written by:
// Last updated:
// etc.
// etc.
///////////////////////////////////////////////////////////////////////////////////

The more pointless stuff like this you can make your patients enforce on themselves the better. Note there is no useful information in the above comment, because the programmer has not supplied any. This is the norm where such headers are required – programmers simply copy and paste an empty one. And if they do make some half-hearted attempt to provide “useful” information in the header, it soon gets completely out of sync with the actual code. And the result? Despair! And we both know how sweet that is! Also, it’s a long shot, but all those slashes may cause visual problems with certain of the human scum.

Anyway, at all costs you must dissuade your patients from writing comments like this:

// Count characters in string terminated by all-bits zero character. 
// Passing a NULL pointer is undefined.
int strlen( const char * s );

Clear, short, can’t easily get outdated when code changes. Comments like this must be stopped, at all costs!

Thirdly, you can try the old trick of getting them to comment every line – once again “coding standards” are your friend here, and definitely not theirs:

int strlen( const char * p ) {      // define function
    int n = 0;      // initialise character count
    while( * p ) {  // while we are not at the end of the string
        p++;        // move to the next character
        n++;        // increment character count
   }                // end while loop
   return n;        // return character count  
}                   // end of function

but I am afraid that even the dimmest human developer is somewhat wise to this.

Fourthly, you should try to convince your temptee that comments are documentation. Of course, you and I know that they are nothing of the sort. Documentation is of necessity a rich medium, including diagrams, examples and similar stuff. But if you can convince the humans that by changing a comment from /* to /** they are creating instantly what technical writers would otherwise have to labour for months over, then that is all to the bad.

And lastly, if all fails, you can almost certainly get some pompous oaf (no shortage of them among developers!) to come out with fatuous advice like “Comment WHY, not HOW” (or possibly vice versa – both are equally meaningless.) This will certainly result in commission of at least two of the Deadly Sins, and may even lead to someone breaking the Sixth Commandment! And how sweet would that be?

Your loving uncle,

PUNCHTAPE
Under Consultant
Demonic Department of Obfuscation and Standardisation

Advertisements


No Responses Yet to “Letter the Seventh – The Curse of Comments”

  1. Leave a Comment

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s


%d bloggers like this: