The best code comments I have seen

/**
 *  This probably returns the id
 **/
// probably??
function getRecordId(){

This code comment was written by John. Every company has a John. He's the master programmer who wreaked havoc years ago at the company. There is no module that doesn't have the finger of John in it. And, years after he has gone, there is no problem in the code that isn't blamed on John.

// Autogenerated, do not edit. All changes will be undone.

John added this to a particularly long and complicated method. This would have been sufficient to deter code meddlers, but he also added a comment at the end of the method:
// I find that if you want to keep someone from messing 
// with your code, add a comment that it's auto generated.

This is my all time favorite:

// 07/12/08 - Temporary logging for debug purposes
// 01/11-10 - temporary????

And, of course, there was a lot of this:
catch (Exception $e){
  // annnnd throw it down a hole
}

No comments:

Post a Comment