Comment On Self-Documenting

Robert W and the rest of the peons in the COGS application group didn't have their own Architecture Team. Their break room wasn't stocked with an endless supply of snacks. In fact, they didn't even have the budget for quarterly "developer retreats". All they had was a CVS repository, a few servers, and a dedication to their client, the COGS group. [expand full text]
« PrevPage 1 | Page 2 | Page 3Next »

Re: Self-Documenting

2009-04-20 09:02 • by sellnosoup (unregistered)
/**
* @param comment FIRST!
*/

Re: Self-Documenting

2009-04-20 09:02 • by First (unregistered)
It's a start

Re: Self-Documenting

2009-04-20 09:03 • by Tony (unregistered)
COMMENT ME!

(Someone was bound to do it...)

Re: Self-Documenting

2009-04-20 09:03 • by Drew (unregistered)
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.

Re: Self-Documenting

2009-04-20 09:06 • by ath (unregistered)
Who needs self-documenting code when you have self-documenting documentation?

Re: Self-Documenting

2009-04-20 09:10 • by Crash Magnet (unregistered)
Mostly Harmless.

Re: Self-Documenting

2009-04-20 09:12 • by Bill (unregistered)
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?



Re: Self-Documenting

2009-04-20 09:12 • by monkeyPushButton (unregistered)
Why stop there?

/**
* CODE ME!
*/

Re: Self-Documenting

2009-04-20 09:14 • by Coward (unregistered)
256827 in reply to 256824
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!***

Re: Self-Documenting

2009-04-20 09:16 • by BoBThESeXy (unregistered)

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

Re: Self-Documenting

2009-04-20 09:26 • by me (unregistered)
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?

Re: Self-Documenting

2009-04-20 09:28 • by Whoevar (unregistered)
256831 in reply to 256826
monkeyPushButton:
Why stop there?

/**
* CODE ME!
*/


Why stop even there?

/**
* DESIGN ME!
*/

Re: Self-Documenting

2009-04-20 09:30 • by Pen Dant (unregistered)
256832 in reply to 256830
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?

Re: Self-Documenting

2009-04-20 09:32 • by Tony (unregistered)
256833 in reply to 256831
Whoevar:
monkeyPushButton:
Why stop there?

/**
* CODE ME!
*/


Why stop even there?

/**
* DESIGN ME!
*/

#define REQUIREMENTS

Re: Self-Documenting

2009-04-20 09:34 • by Blogger (unregistered)
256834 in reply to 256833
Tony:
Whoevar:
monkeyPushButton:
Why stop there?

/**
* CODE ME!
*/


Why stop even there?

/**
* DESIGN ME!
*/

#define REQUIREMENTS


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

Re: Self-Documenting

2009-04-20 09:34 • by JSK (unregistered)
Hmmmm... the JavaDoc lists the param as 'foo' which doesn't match the method param name. JavaDoc warning!

Re: Self-Documenting

2009-04-20 09:36 • by amischiefr
256836 in reply to 256818
"This was the only documentation required by Central IT."

That's more documentation that I usually see.

Re: Self-Documenting

2009-04-20 09:36 • by dpm
256837 in reply to 256821
Drew:
I'd see those and my anal-retentiveness would insist I delete them.


FTFY. You're welcome.

Re: Self-Documenting

2009-04-20 09:38 • by bobbytables (unregistered)
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....

Re: Self-Documenting

2009-04-20 09:40 • by Inhibeo (unregistered)
custom CVS commit hook


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

Re: Self-Documenting

2009-04-20 09:44 • by me (unregistered)
Hey, it could've been worse.

Re: Self-Documenting

2009-04-20 09:44 • by Lars Vargas
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.

Re: Self-Documenting

2009-04-20 09:47 • by Charlie Very Sure (unregistered)
256842 in reply to 256839
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

Re: Self-Documenting

2009-04-20 09:49 • by obediah
256843 in reply to 256830
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.

Re: Self-Documenting

2009-04-20 09:50 • by Dude (unregistered)
256844 in reply to 256834
Blogger:
Tony:
Whoevar:
monkeyPushButton:
Why stop there?

/**
* CODE ME!
*/


Why stop even there?

/**
* DESIGN ME!
*/

#define REQUIREMENTS


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


/**
* make programmer
* /

Re: Self-Documenting

2009-04-20 09:52 • by who the hell knows (unregistered)
256845 in reply to 256844
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..

Re: Self-Documenting

2009-04-20 09:55 • by whatever (unregistered)
256846 in reply to 256844
Tony:
Whoevar:
monkeyPushButton:
Why stop there?

/**
* CODE ME!
*/


Why stop even there?

/**
* DESIGN ME!
*/

#define REQUIREMENTS


/**
* Attain consciousness
* /

Re: Self-Documenting

2009-04-20 09:55 • by Mark (unregistered)
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"...

Re: Self-Documenting

2009-04-20 09:57 • by Nallam (unregistered)
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!";

Re: Self-Documenting

2009-04-20 09:59 • by John (unregistered)
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".

Re: Self-Documenting

2009-04-20 10:02 • by 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?

Re: Self-Documenting

2009-04-20 10:07 • by snoofle
256852 in reply to 256850
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.

Re: Self-Documenting

2009-04-20 10:08 • by dkf
256853 in reply to 256850
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.

Re: Self-Documenting

2009-04-20 10:09 • by Whoevar (unregistered)
256854 in reply to 256850
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.

Re: Self-Documenting

2009-04-20 10:16 • by Tempura (unregistered)
256855 in reply to 256831
Whoevar:
monkeyPushButton:
Why stop there?

/**
* CODE ME!
*/


Why stop even there?

/**
* DESIGN ME!
*/


Why bother with details?

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

Re: Self-Documenting

2009-04-20 10:17 • by Code Dependent
256857 in reply to 256853
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.

Re: Self-Documenting

2009-04-20 10:39 • by my name is missing (unregistered)
Someone make a documentary about this!

Re: Self-Documenting

2009-04-20 10:49 • by narf (unregistered)
256862 in reply to 256846
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
* /

Re: Self-Documenting

2009-04-20 10:54 • by Dazed (unregistered)
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.

Re: Self-Documenting

2009-04-20 10:59 • by WiggyWiggy (unregistered)
256864 in reply to 256831
Whoevar:
monkeyPushButton:
Why stop there?

/**
* CODE ME!
*/


Why stop even there?

/**
* DESIGN ME!
*/



/**
* DOCUMENT THIS!
*/

Re: Self-Documenting

2009-04-20 11:06 • by axus
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.

Re: Self-Documenting

2009-04-20 11:14 • by Jamie (unregistered)
Why didn't they just use the commentator:
http://www.cenqua.com/commentator/

Re: Self-Documenting

2009-04-20 11:18 • by Anonymous Cowherd (unregistered)
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.

Re: Self-Documenting

2009-04-20 11:25 • by Zygo (unregistered)
256871 in reply to 256848
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.

Re: Self-Documenting

2009-04-20 11:50 • by Kuli (unregistered)
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.

Re: Self-Documenting

2009-04-20 12:04 • by Ethan Qix (unregistered)
256875 in reply to 256868
Jamie:
Why didn't they just use the commentator:
http://www.cenqua.com/commentator/


NIH. Therefore completely unreliable.

Re: Self-Documenting

2009-04-20 12:13 • by anonymouse (unregistered)
256877 in reply to 256846
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?

Re: Self-Documenting

2009-04-20 12:16 • by asdf (unregistered)
256878 in reply to 256845
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!

Re: Self-Documenting

2009-04-20 12:24 • by Capt. Obvious (unregistered)
256879 in reply to 256869
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.

Re: Self-Documenting

2009-04-20 12:31 • by Carlos M92 (unregistered)
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.
« PrevPage 1 | Page 2 | Page 3Next »

Add Comment