Comment On Self-Documenting

/**
* @param comment FIRST!
*/

It's a start

COMMENT ME!

(Someone was bound to do it...)

That would work on me... I'd see those and my anal-retentiveness would insist I fix them.

No documentation looks a lot cleaner than bad documentation.

Who needs self-documenting code when you have self-documenting documentation?

Mostly Harmless.

Come on, I've seen much better machine generated documentation than that, mostly in Help dialog boxes:

calculateExpiryScale is a public int method that accepts 1 parameter: keyCode which is a String. It may throw a KeyCodeInvalidException if the KeyCodeInvalidException condition arises during processing.

And really, if you're any good, what more do you need to know?

Why stop there?

/**
* CODE ME!
*/

The worst part is that any good java documentation generator would generated better comments before that garbage was added.

Instead the documentation becomes a useless pile of horse crap!

***!FACE~PALM!***

/*

I don't get it. Why do they bother them with small, stupid things like documentation?

*/

A CVS commit hook that changes the file this is to be committed? CVS hook scripts are not allowed to do this. I can imagine some real crude hack to do it, but other than that?

monkeyPushButton:

Why stop there?

/**
* CODE ME!
*/

Why stop even there?

/**
* DESIGN ME!
*/

me:

A CVS commit hook that changes the file this is to be committed?

You aren't using that new WTF comment commit hook, are you?

Whoevar:

monkeyPushButton:

Why stop there?

/**
* CODE ME!
*/

Why stop even there?

/**
* DESIGN ME!
*/

#define REQUIREMENTS

Tony:

Whoevar:

monkeyPushButton:

Why stop there?

/**
* CODE ME!
*/

Why stop even there?

/**
* DESIGN ME!
*/

#define REQUIREMENTS

/**
* Hire programmer, plug in computer
*/

Hmmmm... the JavaDoc lists the param as 'foo' which doesn't match the method param name. JavaDoc warning!

"This was the only documentation required by Central IT."

That's more documentation that I usually see.

Drew:

I'd see those and my anal-retentiveness would insist I delete them.

FTFY. You're welcome.

If I see one more class with a comment at the top that says "Describes the behaviour of this class" I'm going to cry....

custom CVS commit hook

When you say something like this, the rest of the article just becomes filler.

Hey, it could've been worse.

If Central IT is a division of Central Services, I can understand the need for all documentation to be in order, no matter what.

Robert should be happy that his last name isn't Tuttle, er, Buttle.

Inhibeo:

custom CVS commit hook

When you say something like this, the rest of the article just becomes filler.

PATH=$HOME/bin/cvs_hooks:$PATH

me:

A CVS commit hook that changes the file this is to be committed? CVS hook scripts are not allowed to do this. I can imagine some real crude hack to do it, but other than that?

That's not how thedailywtf.com works. The anonymizer has been upgraded to an anonymizer,embellisher,and grandioser. Like all upgrades, there have been some bugs, and it frequently obfuscates, conflicticates, shuffles, or deletes chunks of text.

Trying to piece together the details of an article can lead to extreme brain trauma, or worse you might actually connect the points into a narrative which would probably break several universal constants, killing us all.

Just chuckle at the moral of the story and come back for more tomorrow.

Blogger:

Tony:

Whoevar:

monkeyPushButton:

Why stop there?

/**
* CODE ME!
*/

Why stop even there?

/**
* DESIGN ME!
*/

#define REQUIREMENTS

/**
* Hire programmer, plug in computer
*/

/**
* make programmer
* /

Dude:

Blogger:

Tony:

Whoevar:

monkeyPushButton:

Why stop there?

/**
* CODE ME!
*/

Why stop even there?

/**
* DESIGN ME!
*/

#define REQUIREMENTS

/**
* Hire programmer, plug in computer
*/

/**
* make programmer
* /

Checking for dependencies..

Tony:

Whoevar:

monkeyPushButton:

Why stop there?

/**
* CODE ME!
*/

Why stop even there?

/**
* DESIGN ME!
*/

#define REQUIREMENTS

/**
* Attain consciousness
* /

At last, back to the good old days of a story that takes less time to read than it did to write. Leaving you with time to go "WTF"...

Standards ask for every entity to be documented in JavaDoc. Now they are, and the check-if-standards-are-met script does not complain. Central IT people aren't bothered with thousands of warnings and are happy again.

The same could be done with:
check-if-standards-are-met > /dev/null; echo "PERFECT!";

I had a wtf like this once. I was moving a bunch of legacy code from one directory to another (and doing a little renaming of classes etc) as part of a reorg, and was told by the chief architect to put empty unit tests in all the files. Apparently the rationale was "it makes it inconvenient for people to not test their code if I insist on empty unit tests".

* @return DOCUMENT ME!
* @throws KeyCodeInvalidException DOCUMENT ME!
*/
public int calculateExpiryScale(String keyCode)

So it couldn't even figure out that the return type is int?

Code Dependent:

* @return DOCUMENT ME!
* @throws KeyCodeInvalidException DOCUMENT ME!
*/
public int calculateExpiryScale(String keyCode)

So it couldn't even figure out that the return type is int?

Knowing the return type of a function, and what it means are not quite the same thing.

Code Dependent:

So it couldn't even figure out that the return type is int?

The javadoc tool itself does that, so its not normal to write that explicitly in doc comments.

Code Dependent:

* @return DOCUMENT ME!
* @throws KeyCodeInvalidException DOCUMENT ME!
*/
public int calculateExpiryScale(String keyCode)

So it couldn't even figure out that the return type is int?

It does not need to. The document generator does this.

Whoevar:

monkeyPushButton:

Why stop there?

/**
* CODE ME!
*/

Why stop even there?

/**
* DESIGN ME!
*/

Why bother with details?

/*
* make many many cash!!1
*/

dkf:

Code Dependent:

So it couldn't even figure out that the return type is int?

The javadoc tool itself does that, so its not normal to write that explicitly in doc comments.

Okay--I'm not familiar with javadoc, but I did see this in the story:

The Documentor, as it turned out, was a custom CVS commit hook that would automatically add JavaDoc to any method definitions lacking them.

I took that to mean that the comments displayed, i.e. "return DOCUMENT ME!", were javadoc and were all the commenting that was to occur.

Someone make a documentary about this!

whatever:

Tony:

Whoevar:

monkeyPushButton:

Why stop there?

/**
* CODE ME!
*/

Why stop even there?

/**
* DESIGN ME!
*/

#define REQUIREMENTS

/**
* Attain consciousness
* /

/** Please remember:
* Set "Evolve into Skynet Cost" at 9999999999
* /

Aaargh! You've reminded me of a WTF I'd mercifully managed to forget. On one of my first jobs we had a mandatory subroutine header-comment template that was about 80 lines. That's right - a subroutine header template, not a file header template. Which meant that each source file consisted of over half boilerplate which was, of course, almost never filled in. And nearly all of which would not have been useful even if it had been filled in.

I attempted to pursuade the person responsible of the futility of this, but his response was something like "that's the standard, quit moaning".

I've often wondered whether people are born that stupid, or if they have to work on it.

Whoevar:

monkeyPushButton:

Why stop there?

/**
* CODE ME!
*/

Why stop even there?

/**
* DESIGN ME!
*/

/**
* DOCUMENT THIS!
*/

It sounds like a good thing to me. No developer time wasted against their will, and a placeholder is there for someone to fill in the next time they work on it.

My main problem with these boilerplate documentation schemes is that it makes the code seem more permanent. Being able to delete or restructure things is good, and investing extra work into something makes you feel less likely to toss it. Especially other people's work.

Why didn't they just use the commentator:
http://www.cenqua.com/commentator/

Funnily enough... Doxygen likes to utterly ignore anything that doesn't have a doc comment. Throwing in an empty or duff doc comment will make Doxygen generate much better documentation than it would otherwise create.

Nallam:

Standards ask for every entity to be documented in JavaDoc. Now they are, and the check-if-standards-are-met script does not complain. Central IT people aren't bothered with thousands of warnings and are happy again.

The same could be done with:
check-if-standards-are-met > /dev/null; echo "PERFECT!";

check-if-standards-are-met might crash, hang, write data on stderr, or interfere with the operation of some other program on the build machine. Best to just remove it completely, and skip to the echo command.

You can do the same thing with the build system, unit tests, bug tracker, and systems monitoring tools too. It really makes life much, much easier.

I think they're using Checstyle as as code analysis tool (http://en.wikipedia.org/wiki/Checkstyle). Methods that aren't commented correctly will appear as a compile error or warning.

All they needed to do is to generate comments that satisfy Checkstyle.

Checkstyle is a great tool, but only if you use it wisely.

Jamie:

Why didn't they just use the commentator:
http://www.cenqua.com/commentator/

NIH. Therefore completely unreliable.

whatever:

Tony:

Whoevar:

monkeyPushButton:

Why stop there?

/**
* CODE ME!
*/

Why stop even there?

/**
* DESIGN ME!
*/

#define REQUIREMENTS

/**
* Attain consciousness
* /

/**
* FUCK
* /

Well, you were just asking for this, weren't you?

who the hell knows:

Dude:

Blogger:

Tony:

Whoevar:

monkeyPushButton:

Why stop there?

/**
* CODE ME!
*/

Why stop even there?

/**
* DESIGN ME!
*/

#define REQUIREMENTS

/**
* Hire programmer, plug in computer
*/

/**
* make programmer
* /

Checking for dependencies..

Customer: I have a great idea!

Anonymous Cowherd:

Doxygen likes to utterly ignore anything that doesn't have a doc comment.

Doxygen has a flag to ignore undocumented functions that is on by default. Unfortunately, I'm don't recall what it is, but if you turn it on, I would imagine it would solve your problem.

So Central IT was worried that *only* 53.8% of the code was documented? How about the system I am currently working on, with entire classes that don't have any useful comment whatsoever?

What matters most is that classes and members have good names, and that comments have useful information where it's needed - not that you attach comments to every single member.