Self-Documenting

« Return to Article
  • sellnosoup 2009-04-20 09:02
    /**
    * @param comment FIRST!
    */
  • First 2009-04-20 09:02
    It's a start
  • Tony 2009-04-20 09:03
    COMMENT ME!

    (Someone was bound to do it...)
  • Drew 2009-04-20 09:03
    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 2009-04-20 09:06
    Who needs self-documenting code when you have self-documenting documentation?
  • Crash Magnet 2009-04-20 09:10
    Mostly Harmless.
  • Bill 2009-04-20 09:12
    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 2009-04-20 09:12
    Why stop there?

    /**
    * CODE ME!
    */
  • Coward 2009-04-20 09:14
    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 2009-04-20 09:16

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

  • me 2009-04-20 09:26
    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 2009-04-20 09:28
    monkeyPushButton:
    Why stop there?

    /**
    * CODE ME!
    */


    Why stop even there?

    /**
    * DESIGN ME!
    */
  • Pen Dant 2009-04-20 09:30
    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 2009-04-20 09:32
    Whoevar:
    monkeyPushButton:
    Why stop there?

    /**
    * CODE ME!
    */


    Why stop even there?

    /**
    * DESIGN ME!
    */

    #define REQUIREMENTS
  • Blogger 2009-04-20 09:34
    Tony:
    Whoevar:
    monkeyPushButton:
    Why stop there?

    /**
    * CODE ME!
    */


    Why stop even there?

    /**
    * DESIGN ME!
    */

    #define REQUIREMENTS


    /**
    * Hire programmer, plug in computer
    */
  • JSK 2009-04-20 09:34
    Hmmmm... the JavaDoc lists the param as 'foo' which doesn't match the method param name. JavaDoc warning!
  • amischiefr 2009-04-20 09:36
    "This was the only documentation required by Central IT."

    That's more documentation that I usually see.
  • dpm 2009-04-20 09:36
    Drew:
    I'd see those and my anal-retentiveness would insist I delete them.


    FTFY. You're welcome.
  • bobbytables 2009-04-20 09:38
    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 2009-04-20 09:40
    custom CVS commit hook


    When you say something like this, the rest of the article just becomes filler.
  • me 2009-04-20 09:44
    Hey, it could've been worse.
  • Lars Vargas 2009-04-20 09:44
    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 2009-04-20 09:47
    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
  • obediah 2009-04-20 09:49
    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 2009-04-20 09:50
    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 2009-04-20 09:52
    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 2009-04-20 09:55
    Tony:
    Whoevar:
    monkeyPushButton:
    Why stop there?

    /**
    * CODE ME!
    */


    Why stop even there?

    /**
    * DESIGN ME!
    */

    #define REQUIREMENTS


    /**
    * Attain consciousness
    * /
  • Mark 2009-04-20 09:55
    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 2009-04-20 09:57
    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 2009-04-20 09:59
    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".
  • Code Dependent 2009-04-20 10:02
    * @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?
  • snoofle 2009-04-20 10:07
    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.
  • dkf 2009-04-20 10:08
    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.
  • Whoevar 2009-04-20 10:09
    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.
  • Tempura 2009-04-20 10:16
    Whoevar:
    monkeyPushButton:
    Why stop there?

    /**
    * CODE ME!
    */


    Why stop even there?

    /**
    * DESIGN ME!
    */


    Why bother with details?

    /*
    * make many many cash!!1
    */
  • Code Dependent 2009-04-20 10:17
    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 2009-04-20 10:39
    Someone make a documentary about this!
  • narf 2009-04-20 10:49
    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 2009-04-20 10:54
    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 2009-04-20 10:59
    Whoevar:
    monkeyPushButton:
    Why stop there?

    /**
    * CODE ME!
    */


    Why stop even there?

    /**
    * DESIGN ME!
    */



    /**
    * DOCUMENT THIS!
    */
  • axus 2009-04-20 11:06
    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.
  • Jamie 2009-04-20 11:14
    Why didn't they just use the commentator:
    http://www.cenqua.com/commentator/
  • Anonymous Cowherd 2009-04-20 11:18
    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 2009-04-20 11:25
    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.
  • Kuli 2009-04-20 11:50
    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.
  • Ethan Qix 2009-04-20 12:04
    Jamie:
    Why didn't they just use the commentator:
    http://www.cenqua.com/commentator/


    NIH. Therefore completely unreliable.
  • anonymouse 2009-04-20 12:13
    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 2009-04-20 12:16
    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 2009-04-20 12:24
    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 2009-04-20 12:31
    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 2009-04-20 12:34
    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
    */
  • seantellis 2009-04-20 12:46
    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
    */
  • tezoatlipoca 2009-04-20 12:51
    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.
  • Herby 2009-04-20 12:58
    Look this documentation stuff is pretty easy. Just follow the example:
    http://thedailywtf.com/Articles/Very,_Very_Well_Documented.aspx
  • IV 2009-04-20 13:02
    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 2009-04-20 13:07
    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.
  • Mii 2009-04-20 13:31
    /*
    * write clever DailyWTF comments !
    */
  • CynicalTyler 2009-04-20 13:53
    Mii:
    /*
    * write clever DailyWTF comments !
    */

    You must be new here. I remember when I had such unbridled optimism.
  • snoofle 2009-04-20 13:54
    seantellis:
    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
    */
    /**
    
    * CREATE SUPREME BEING
    */
  • hatterson 2009-04-20 13:59
    Franz Kafka:
    amischiefr:
    "This was the only documentation required by Central IT."

    That's more documentation that I usually see.
    That's no use, so it's basically undocumented.
    Regardless of how small it is, there is a difference between "basically undocumented" and "undocumented"
  • Dave 2009-04-20 14:00
    Stick a @TODO Document on there and it's not really a bad idea, assuming someone looks through them.
  • Qavi 2009-04-20 14:08
    Comment on this!
  • Code Dependent 2009-04-20 14:46
    Dave:
    Stick a @TODO Document on there and it's not really a bad idea, assuming someone looks through them.
    //TODO: add TODO notifications
  • neveralull 2009-04-20 15:15
    These headers, once documented, contain no useful information, and worse - are never updated when the code changes. We end up with documentation that is just plain wrong.
    /**
    * calculateExpiryScale
    *
    * @param keyCode - the key code
    * @return int - the Expiry scale
    * @throws KeyCodeInvalidException - indicates an invaliad key Code (spelling error intentional) */
    public int calculateExpiryState(int keyCode, String keyDescr)
    throws KeyIdInvalidException {

  • pink_fairy 2009-04-20 15:29
    Kuli:
    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.
    Oh, super, the anti-Knuth Pattern. "Compile error or warning?"

    With a "tool" like this, you're practically insisting that comments are specifically generated "to satisfy Checkstyle." Way to go, sucking all the life out of the development process.

    Mind you, it's in Java, so I don't suppose anybody would notice.
  • A. Cube 2009-04-20 15:31
    Man. I wish this was as bad as it got where I work. If "central IT" has people who know what a CVS hook is or that they care that anything is documented, they are better than most of the people I work with.
  • Pet 2009-04-20 15:48
    A positive point of mandatory comments for public members is that it pushes towards avoiding making any random routine public. If writing a comment is a bigger hassle than cleaning up the class to avoid unnecessary exposing of its guts, then that even may become a good thing.

    At least it works for me that way.
  • TheRider 2009-04-20 16:02
    I have plenty of unit tests like this:

    /**
    * Tests the functionality implied by the method name
    */
    public void testSaveCustomerObject() {
    ...
    }
  • Buddy 2009-04-20 16:10
    Personally, I try to make code self-documenting. If you're making the code so clever that it can't be understood without a comment, then something needs to be redesigned. In C and C++, because you have access to so many low level details, there is a temptation to resort to cleverness to get the job done.

    I once thought about designing a language where there is no provision for explicit comments. Exceptions would be allowed to accommodate wonky third party APIs (e.g. declare [function] [library] [comment]), and debug tracing code (e.g. debug([comment])). Authorship, copyright and related would be an explicit component of a class, function, etc.
  • AB 2009-04-20 16:17
    Whereas it might be complicated to discover which members are not documented at all, depending on your IDE, or lack of one, it's a relatively simple search to find all instances of DOCUMENT ME, and correct them.
  • pink_fairy 2009-04-20 16:48
    AB:
    Whereas it might be complicated to discover which members are not documented at all, depending on your IDE, or lack of one, it's a relatively simple search to find all instances of DOCUMENT ME, and correct them.
    Which do you prefer?

    (a) DRINK ME or
    (b) EAT ME?

    I know which one 99% of the programmers on your project would recommend.
  • dkf 2009-04-20 17:21
    Code Dependent:
    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.
    The comments are documentation comments that provide additional information that allow the javadoc tool to do a better job when generating HTML from the class. They're not exactly rocket science (given that the fancy features aren't being used here). Left to its own devices, javadoc actually manages to do a reasonable job of building docs from source, but it doesn't know anything about the purpose of the code (duh!) so its automatic output is rather less useful than you might hope for; it really needs those doc comments done properly to be actually useful.

    Sticking "DOCUMENT ME!" all over the place doesn't help. Treating that as a solution... <sigh>

    Mind you, I once had to deal with a codebase where every getFoobar() method was "documented" with the obvious "get foobar", with no mention of what a foobar was, why you might want one, or whether you were getting a singleton, a new instance, or something from a pool. You know, anything that might have actually been useful.
  • Code Dependent 2009-04-20 17:58
    dkf:
    Mind you, I once had to deal with a codebase where every getFoobar() method was "documented" with the obvious "get foobar", with no mention of what a foobar was, why you might want one, or whether you were getting a singleton, a new instance, or something from a pool. You know, anything that might have actually been useful.
    I'm familiar with the mentality. Stuff like:

    i++; // Increment i by one

    I recently encountered a web app from the ASP.Net 1.1 days, when all the server controls were declared in the codebehind (before VS started hiding them in partial classes). Someone had gone through a list of about 30 controls and commented above each one exactly what the control was. So it looked like this, repeated 30 times:

    // System.Web.UI.WebControls.Textbox
    Protected System.Web.UI.WebControls.Textbox txtFirstName;
  • Joe Mama 2009-04-20 18:01
    neveralull:
    These headers, once documented, contain no useful information, and worse - are never updated when the code changes. We end up with documentation that is just plain wrong.


    Bingo. Javadoc will generate very useful information without you putting in what are most often redundant comments (or lies, as neveralull suggests). You just have to learn how to create method and argument names that are meaningful (which also means that you have to understand SRP so that you can compose methods that can be concisely described). (Sadly, it doesn't happen often, as too many of us don't have a clue about cohesion.)
  • Joe Mama 2009-04-20 18:02
    Pet:
    A positive point of mandatory comments for public members is that it pushes towards avoiding making any random routine public.


    There are chuckleheads who insist that even non-public methods have javadoc comments...
  • lolwtf 2009-04-20 18:32
    Aw, I was expecting the code to parse the source and replace those tags with actual documentation.
  • Matt 2009-04-20 18:54
    Wow, that is hilarious. I hope they didn't pay much for that.

    Matt
    VinSolutions
    Automotive CRM Software
  • Bob 2009-04-20 19:21
    Joe Mama:
    There are chuckleheads who insist that even non-public methods have javadoc comments...

    You have to be kidding.

    Everyone knows that maintenance programmers who have to deal with non-public methods are psychic, and know that the method was supposed to do long before you've even written it. What would they need comments for?

    Next thing you know, some chucklehead will claim that decent documentation tools can produce different output depending on whether you ask for public documentation or all documentation, and that's insane.
  • Cooksey 2009-04-20 19:35
    I can clearly remember how offended I was by the original Sony Playstation documentation where there was minimal documentation of the functionality and most of the functions had this line:

    Return: This function returns a value

    Needless to say there was nothing self documenting about the code and there was much whining from all of the developer groups with which I was working.

    When I got the chance to write the audio os for the sega Dreamcast I jumped at it despite Segas terrible reputation just so that I could spare my friends that kind of lame ass shite.

    I have no opinion whatsoever. none.

    Captcha: immitto
  • np 2009-04-20 19:39
    snoofle:
    seantellis:
    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
    */
    /**
    
    * CREATE SUPREME BEING
    */


    /**
    * CREATE SUPREME BEING FACTORY
    */
  • Ken B 2009-04-20 19:42
    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
    * /
    make: *** No rule to make target `programmer'. Stop.
  • Anon 2009-04-20 19:56
    1.
    Tony:
    COMMENT ME!


    2. ?
    3. Profit!
  • Kaenneth 2009-04-20 20:29
    I found the 'Ghostdoc' tool for C# very useful for starting comments; but more useful to identify poorly named classes/methods/parameters.

    It comments methods like 'FileOpen" as "Opens the File"

    If it couldn't parse the name, then a real (say, non native english speaker) person might have difficulty... 'DisConnect' becomes "Dises the connect."

    http://www.roland-weigelt.de/ghostdoc/
  • Hans 2009-04-20 20:55
    Actually, I think this is a pretty good idea. These sort of comments will show up as a reminder to document and pick out who it was that didn't document their code for a bit of a scolding to finish off the job.
  • I_AM_A_RETARDED 2009-04-20 21:11
    Come to my party
    Come sing along
    Come watch me kick myself
    in the balls!

    And then I'm gonna kick
    my dog in the balls!
  • transverbero 2009-04-20 21:57
    np:
    snoofle:
    seantellis:
    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
    */
    /**
    
    * CREATE SUPREME BEING
    */


    /**
    * CREATE SUPREME BEING FACTORY
    */
    /**
    
    * CREATE SUPREME BEING FACTORY BUILDER
    */
  • praesent 2009-04-20 22:00
    Jamie:
    Why didn't they just use the commentator:
    http://www.cenqua.com/commentator/
    LOL! I especially love the "PairOn" chair in the sidebar.
  • Brandon 2009-04-21 00:13
    Ken B:
    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
    * /
    make: *** No rule to make target `programmer'. Stop.

    -Be-
  • Someone 2009-04-21 04:40
    anonymouse:
    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?

    You got this in the wrong place. It should have been a reply to the "make programmer" comment.
  • Someone 2009-04-21 04:52
    Kaenneth:
    I found the 'Ghostdoc' tool for C# very useful for starting comments; but more useful to identify poorly named classes/methods/parameters.

    It comments methods like 'FileOpen" as "Opens the File"

    Perhaps you mean "Files the Open"?

    Kaenneth:
    If it couldn't parse the name, then a real (say, non native english speaker) person might have difficulty... 'DisConnect' becomes "Dises the connect."

    Or is this "Connects the Dis"?
  • Chris 2009-04-21 04:55
    snoofle:
    seantellis:
    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
    */
    /**
    
    * CREATE SUPREME BEING
    */


    Error: SUPREME BEING is null or not an object
  • AnyonymousOrSmthing 2009-04-21 05:11
    transverbero:
    np:
    snoofle:
    seantellis:
    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
    */
    /**
    
    * CREATE SUPREME BEING
    */


    /**
    * CREATE SUPREME BEING FACTORY
    */
    /**
    
    * CREATE SUPREME BEING FACTORY BUILDER
    */


    /*
    * CREATE SUPREME BEING FACTORY BUILDER PATTERN
    *
    */
  • Sindri 2009-04-21 06:02
    53.8% javadoc, that's a lot!
  • imu 2009-04-21 07:44
    snoofle:
    /**
    
    * CREATE SUPREME BEING
    */

    Wouldn't SUPREME BEING be a singleton?
  • Taka 2009-04-21 07:46
    The real WTF is that they didn't stick a TODO in there. At least without a Javadoc, an IDE could tell you one was missing. Now they're worse off than no documentation.
  • OldTechSupport 2009-04-21 07:57
    Buddy:
    Personally, I try to make code self-documenting. If you're making the code so clever that it can't be understood without a comment, then something needs to be redesigned. In C and C++, because you have access to so many low level details, there is a temptation to resort to cleverness to get the job done.

    No, no, no, NO! The issue isn't necessarily that the code is "so clever" that it can't be understood, it's whether you can understand the GOAL of the code. Code can be simple, yet wrong for the intended purpose.

    As a vendor, I've inherited products that had no decent documentation, and had to call friendly customers to ask whether certain behavior was correct or not -- it wasn't that I couldn't understand what it was *doing*, it was that without doc, I couldn't tell if that was what I *wanted* it to do.

    I see this "Read the code, don't need comments" position again and again, and I'm sorry, but it's flat-out naive and shows a lack of experience in the real world. And it scares the hell out of me, having lived the nightmare too many times.
  • OldTechSupport 2009-04-21 08:01
    Sindri:
    53.8% javadoc, that's a lot!

    Yes, almost up to the level of appropriate commenting.

    Well-documented code, in my experience, is at least 50% comments.
  • Joe Mama 2009-04-21 09:04
    Bob:
    Next thing you know, some chucklehead will claim that decent documentation tools can produce different output depending on whether you ask for public documentation or all documentation, and that's insane.


    Next thing you know, some chucklehead programmer who insists on wasting time with formatted comments for private methods might actually take the time to fire up a web page and navigate to the appropriate spot in the pretty web pages to read such a comment.
  • Joe Mama 2009-04-21 09:06
    Bob:
    Everyone knows that maintenance programmers who have to deal with non-public methods are psychic, and know that the method was supposed to do long before you've even written it. What would they need comments for?


    This puts you in the class of people who don't understand cohesion.
  • IByte 2009-04-21 09:59
    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?
    CVS is a real crude hack...
  • Buddy 2009-04-21 10:47
    OldTechSupport:
    Sindri:
    53.8% javadoc, that's a lot!

    Yes, almost up to the level of appropriate commenting.

    Well-documented code, in my experience, is at least 50% comments.


    Used to feel the same way, until I worked at a place where I was required to include contact information in the source. I realized then that:

    - nobody reads specs
    - nobody reads comments
    - some people read code
    - everybody sends e-mails
    - everybody calls phone numbers

    If where I'm working requires comments, I just run a utility to stick a block at each function, and permute the declaration - e.g. STATUS BusterBrown::LikesWarmMilk(const char *you_bet) -> LikesWarmMilk for BusterBrown, takes const char pointer and returns STATUS.
  • OldTechSupport 2009-04-21 12:07
    Buddy:

    Used to feel the same way, until I worked at a place where I was required to include contact information in the source. I realized then that:

    - nobody reads specs
    - nobody reads comments
    - some people read code
    - everybody sends e-mails
    - everybody calls phone numbers

    If where I'm working requires comments, I just run a utility to stick a block at each function, and permute the declaration - e.g. STATUS BusterBrown::LikesWarmMilk(const char *you_bet) -> LikesWarmMilk for BusterBrown, takes const char pointer and returns STATUS.

    Please don't let that discourage you. Just because one site had psychotic requirements doesn't make decent comments a bad idea...
  • Ronan 2009-04-21 13:42
    Anyone care to share an example of checkstyle (or whatever was used) being called in the exact manner that this document refers to ?

    I REALLY need to set up something like this in my company ASAP

    Cheers,
    Ro
  • dkf 2009-04-21 17:50
    imu:
    Wouldn't SUPREME BEING be a singleton?
    Not at all! In India or ancient Greece or Egypt, it's not a singleton at all. And in other parts of the world, it's abstract, with no instances (other than Bruce Schneier, of course).

    This sounds like a job for localization of your code. Run the program source through a message catalog before compiling...
  • rfsmit 2009-04-21 18:51
    snoofle:
    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.

    Why do you think it's called "code"?
  • rfsmit 2009-04-21 18:52
    dkf:
    imu:
    Wouldn't SUPREME BEING be a singleton?
    Not at all! In India or ancient Greece or Egypt, it's not a singleton at all. And in other parts of the world, it's abstract, with no instances (other than Bruce Schneier, of course).

    You forgot null.
  • joelkatz 2009-04-22 03:31
    I see both sides on this one.

    On the pro side, the tool meets the absurd requirement. The tool points out what you need to document and lays it out in the right format.

    On the con side, the tool bypasses the point of the requirement. The tool also crowds the code with useless nonsense.

    The real WTF is, of course, the requirement that the code appear to have comments per some automated test rather than a requirement that it actually be appropriately commented.

    The over-arching, all-inclusive WTF is the idea that code can be usefully measured using metrics calculated by automated code-scanning tools.
  • Alex 2009-04-22 08:08

    /**
    * @todo DOCUMENT ME!
    */
  • Ronan 2009-04-23 05:23
    Ronan:
    Anyone care to share an example of checkstyle (or whatever was used) being called in the exact manner that this document refers to ?

    I REALLY need to set up something like this in my company ASAP

    Cheers,
    Ro


    I jsut found this ... http://www.cive.de/projects/javadocchecker/

    It works superbly !
    (Although I had to edit the properties file to tell it not to check fields)
  • rong1982 2009-04-23 11:56
    搬家搬家 搬家公司在職進修 婚紗 新娘秘書 汽車旅館 彩妝造型 新娘秘書 票貼 室內設計 室內設計 外遇 抓姦 應收帳款 徵信 徵信社 外遇 徵信 徵信社 外遇 植牙 牙齒矯正 坐月子 宜蘭民宿 婚禮佈置 宜蘭民宿推薦 催眠 派報 太陽能熱水器 Shade sail nike shoes 關鍵字廣告 租屋 搬家 搬家 買房子 花蓮民宿 花蓮民宿 花店 租房子 xo醬 房屋貸款 搬家公司 減肥 減重 床墊 創業加盟 團體服 學英文 英文 補習班 勞工體檢 資源回收 生日禮物 團體服 團體制服 班服 塑膠 日立家電 飾品批發 MBA 在职研究生 在职博士 电动隔膜泵 自吸泵 化工泵 离心泵 磁力泵 螺杆泵 水泵 隔膜泵 气动隔膜泵 婚禮佈置 婚禮佈置 婚禮佈置 酒店經紀 酒店經紀 班服配件 團體服配件 團體服 班服 團體服 班服 團體服 室內設計公司 室內設計公司 室內設計公司 金門高梁酒變頻洗衣機學英文
  • rong1982 2009-04-23 11:56
  • zerocon 2009-04-23 12:30
    AnyonymousOrSmthing:
    transverbero:
    np:
    snoofle:
    seantellis:
    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
    */
    /**
    
    * CREATE SUPREME BEING
    */


    /**
    * CREATE SUPREME BEING FACTORY
    */
    /**
    
    * CREATE SUPREME BEING FACTORY BUILDER
    */


    /*
    * CREATE SUPREME BEING FACTORY BUILDER PATTERN
    *
    */

    /*
    * PLZ KILL ME KTHANX
    */
  • Robot-until-proven-human 2009-04-24 15:16
    my name is missing:
    Someone make a documentary about this!


    The book is already written: "JPod" by Douglas Coupland.

    http://en.wikipedia.org/wiki/JPod

    --
  • SatanClaus 2009-04-27 07:46
    Nothing like idiots to tell you that you are documenting things wrong. Then they provide a fix. And don't use the standard JavaDoc TODO tag in the fix.
  • Jay 2009-04-27 12:49
    dkf:
    imu:
    Wouldn't SUPREME BEING be a singleton?
    Not at all! In India or ancient Greece or Egypt, it's not a singleton at all. And in other parts of the world, it's abstract, with no instances (other than Bruce Schneier, of course).


    No, in some times and places people THINK that there can be multiple instances of supreme beings, while in others people think that there can be only one, and others think there is none at all. But clearly one group is right and the others are wrong. Just because there is confusion over the specifications doesn't mean that there is no right answer! Is this how you write your code? "The marketing department says that 'price' is an attribute of the Product entity, which would make the price the same for all sales at all stores, but the store managers say that it is an attribute of Sale because salesman can negotiate on-the-spot discounts. So I guess that means there is no right answer and we can throw it where ever we like!"

  • Buffled 2009-04-28 14:31
    Bill:
    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?

    If you're any good the function signature tells you that already. WIthout the pointless paragraphs...
  • marco 2009-04-28 15:21
    /**
    * Kill flanders!
    */
  • jackon 2009-05-20 01:01
    uggs, with a legendary brand, first to see the snow ugg boots ,Ugg people will not Ben Ben flu cartoon form, and is a boots, as a result of many European and American film star has adequate Gordon Street Ugg snow boots and a pretty popular in Europe and America look like the earth, Ugg blowing sustained winds of the popular Madden, in Japan, Taiwan has a lot of fans Ugg.
  • cindy 2011-02-21 04:06
    find for all kinds of watches and women handbags .

    A Lange & Sohne watches
    http://replica038.com/a-lange-sohne-watches.html

    Audemars Piguet watches
    http://replica038.com/audemars-piguet-watches.html
  • neminem 2011-10-28 16:40
    Late comment: I'd much rather autogenerated comments that just say "please put real comments here", than autogenerated comments that look like real comments until you actually read them, at which point you realize they're useless, and in some cases hilarious gibberish. Some real examples from our project, for the benefit of anyone else random wandering through old comments:

    /// <summary>
    /// Determines whether [is equal to] [the specified x].
    /// </summary>
    /// <param name="x">The x.</param>
    /// <param name="y">The y.</param>
    /// <returns>
    /// <c>true</c> if [is equal to] [the specified x]; otherwise, <c>false</c>.
    /// </returns>
    private bool IsEqualTo(List<CreateTokenInformation> x, List<CreateTokenInformation> y)

    /// <summary>
    /// Datas the grid view cell value changed.
    /// </summary>
    protected abstract void DataGridViewCellValueChangedCore(DataGridViewCellEventArgs e);

    /// <summary>
    /// Languages the comparer.
    /// </summary>
    /// <param name="first">The first.</param>
    /// <param name="second">The second.</param>
    /// <returns>
    /// Language comparer and returns a <seealso cref="Int32"/>.
    /// </returns>
    private int LanguageComparer(Display<object> first, Display<object> second)

    /// <summary>
    /// Pages the changed.
    /// </summary>
    private void PageChanged(object sender, EventArgs e)