No comment

Flashback to the days when this IT pilot fish is still in college, and he's proud to say most of his instructors are extremely good.

That's most of them. "On the first day of class in my senior year, one particular instructor stressed how important it was to thoroughly document our code," says fish. "Most of us already knew this -- it was an upper-level programming course -- but he said we'd lose at least a full letter grade for inadequately documented code in our assignments."

No problem, fish thinks. He's working his way through school as a professional programmer, and he's learned good documentation habits from some very talented mentors.

But when his first programming assignment comes back, the grade is low and there's a note: "Poorly Documented."

So fish goes all-out on his next assignment, writing a very detailed explanation for each parameter, algorithm and return value. Result: low grade and "Poorly Documented."

For the third program assignment, fish's comments are all but a textbook on what the program does and how it's supposed to do it. But again: low grade and "Poorly Documented."

"I went to the instructor's office and asked what was wrong with my documentation," fish says. "He glanced at the printout and said, 'What does this line do? See, you didn't document it.'

"I looked where he was pointing. It was the return statement at the end of a function. Extensive comments describing the function filled every preceding line, but the very last line had no comment."

Instructor points out other trivial lines with no comments. "How do I know what any of these lines do if you don't comment them?" he tells fish. "Your grade on this assignment was very generous, considering that you were so lazy in your documentation."

Baffled fish tries explaining that the program is fully documented in the existing comments, but the instructor clearly isn't listening.

So for his next assignment, fish comments his code something like this:

function float DoSomething(int A, int B); //Start of function
declare int X; //Declare X
declare int Y; //Declare Y
X = A + 1; //Do some math
Y = B + 1; //Sheep eat grass
return (X * Y); //Go home

Sighs fish, "He gave it a grade of A+. For the rest of the course, that was how I documented all my programs. I was never quite brave enough to write what I thought of him as an instructor, just in case he might accidentally read the comments one day, but I did put in nursery rhymes and shopping lists.

"Despite the low grades at the beginning, I passed his class with an A."

Document your true tale of IT life for Sharky. Send me your story at sharky@computerworld.com, and you'll snag a snazzy Shark shirt if I use it. Add your comments below, and read some great old tales in the Sharkives.

Get your daily dose of out-takes from the IT Theater of the Absurd delivered directly to your Inbox. Subscribe now to the Daily Shark Newsletter.

To express your thoughts on Computerworld content, visit Computerworld's Facebook page, LinkedIn page and Twitter stream.
Windows 10 annoyances and solutions
Shop Tech Products at Amazon
Notice to our Readers
We're now using social media to take your comments and feedback. Learn more about this here.