• First (unregistered)

    It's a start

  • Tony (unregistered)

    COMMENT ME!

    (Someone was bound to do it...)

  • 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.

  • ath (unregistered)

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

  • Crash Magnet (unregistered)

    Mostly Harmless.

  • 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?

  • monkeyPushButton (unregistered)

    Why stop there?

    /**

    • CODE ME! */
  • Coward (unregistered) in reply to Crash Magnet

    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!

  • BoBThESeXy (unregistered) 
    /*
I don't get it. Why do they bother them with small, stupid things like documentation?
*/
  • 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?

  • Whoevar (unregistered) in reply to monkeyPushButton
    monkeyPushButton:
    Why stop there?

    /**

    • CODE ME! */

    Why stop even there?

    /**

    • DESIGN ME! */
  • Pen Dant (unregistered) in reply to 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?
  • Tony (unregistered) in reply to Whoevar
    Whoevar:
    monkeyPushButton:
    Why stop there?

    /**

    • CODE ME! */

    Why stop even there?

    /**

    • DESIGN ME! */
    #define REQUIREMENTS
  • Blogger (unregistered) in reply to Tony
    Tony:
    Whoevar:
    monkeyPushButton:
    Why stop there?

    /**

    • CODE ME! */

    Why stop even there?

    /**

    • DESIGN ME! */
    #define REQUIREMENTS

    /**

    • Hire programmer, plug in computer */
  • JSK (unregistered)

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

  • (cs)

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

    That's more documentation that I usually see.

  • (cs) in reply to Drew
    Drew:
    I'd see those and my anal-retentiveness would insist I delete them.

    FTFY. You're welcome.

  • 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....

  • Inhibeo (unregistered)
    custom CVS commit hook

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

  • me (unregistered)

    Hey, it could've been worse.

  • (cs)

    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.

  • Charlie Very Sure (unregistered) in reply to Inhibeo
    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

  • (cs) in reply to me
    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.

  • Dude (unregistered) in reply to Blogger
    Blogger:
    Tony:
    Whoevar:
    monkeyPushButton:
    Why stop there?

    /**

    • CODE ME! */

    Why stop even there?

    /**

    • DESIGN ME! */
    #define REQUIREMENTS

    /**

    • Hire programmer, plug in computer */

    /**

    • make programmer
    • /
  • who the hell knows (unregistered) in reply to Dude
    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..

  • whatever (unregistered) in reply to Dude
    Tony:
    Whoevar:
    monkeyPushButton:
    Why stop there?

    /**

    • CODE ME! */

    Why stop even there?

    /**

    • DESIGN ME! */
    #define REQUIREMENTS

    /**

    • Attain consciousness
    • /
  • 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"...

  • 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!";

  • 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".

  • (cs)
    * @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?
  • (cs) in reply to Code Dependent
    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.
  • (cs) in reply to Code Dependent
    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.
  • Tempura (unregistered) in reply to Whoevar
    Whoevar:
    monkeyPushButton:
    Why stop there?

    /**

    • CODE ME! */

    Why stop even there?

    /**

    • DESIGN ME! */

    Why bother with details?

    /*

    • make many many cash!!1 */
  • (cs) in reply to dkf
    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.
  • my name is missing (unregistered)

    Someone make a documentary about this!

  • narf (unregistered) in reply to whatever
    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
    • /
  • 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.

  • WiggyWiggy (unregistered) in reply to Whoevar
    Whoevar:
    monkeyPushButton:
    Why stop there?

    /**

    • CODE ME! */

    Why stop even there?

    /**

    • DESIGN ME! */

    /**

    • DOCUMENT THIS! */
  • (cs)

    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.

  • 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.

  • Zygo (unregistered) in reply to Nallam
    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.

  • anonymouse (unregistered) in reply to whatever
    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?

  • asdf (unregistered) in reply to who the hell knows
    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!

  • Capt. Obvious (unregistered) in reply to Anonymous Cowherd
    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.
  • 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.

  • Zach Bora (unregistered) in reply to asdf
    asdf:
    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!

    /**

    • Create Company */
  • (cs) in reply to asdf

    Just to put an end to the cascade, I submit a final entry, inspired by Carl Sagan's "apple pie from scratch" recipe:

    /**
 * DOCUMENT ME!
 */

/**
 * CODE ME!
 */

...snip me...

/**
 * CREATE UNIVERSE
 */
  • (cs)
    Jamie:
    Why didn't they just use the commentator: http://www.cenqua.com/commentator/

    Damn. I was genuinely disappointed to realize at the bottom that Commentator 1.0 doesn't exist. :(

    Thanks for that though.

  • IV (unregistered) in reply to Drew
    Drew:
    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.

    Mine would too. I would do a replace all "DOCUMENT ME !" with "This feature is currently undocument." It would look a lot cleaner, and it would take almost no additional effort.

  • Franz Kafka (unregistered) in reply to amischiefr
    amischiefr:
    "This was the only documentation required by Central IT."

    That's more documentation that I usually see.

    Not really - it just reiterates the method signature, which you already have. That's no use, so it's basically undocumented. What might be actually useful is a comment about what the method is for.

Leave a comment on “Self-Documenting”

Log In or post as a guest

Replying to comment #:

Log Out

« Return to Article