• Mii (unregistered)

    /*

    • write clever DailyWTF comments ! */
  • CynicalTyler (unregistered) in reply to Mii
    Mii:
    /* * write clever DailyWTF comments ! */
    You must be new here. I remember when I had such unbridled optimism.
  • (cs) in reply to seantellis
    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
*/
  • (cs) in reply to Franz Kafka
    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"

  • Qavi (unregistered)

    Comment on this!

  • (cs)
    Dave:
    Stick a @TODO Document on there and it's not really a bad idea, assuming someone looks through them.
    //TODO: add TODO notifications
  • (cs)
    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 (unregistered)

    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 (unregistered)

    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.

  • (cs) in reply to Pet

    I have plenty of unit tests like this:

    /**

    • Tests the functionality implied by the method name */ public void testSaveCustomerObject() { ... }
  • Buddy (unregistered)

    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 (unregistered)

    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.

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

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

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

  • (cs)

    Aw, I was expecting the code to parse the source and replace those tags with actual documentation.

  • Bob (unregistered) in reply to Joe Mama
    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 (unregistered)

    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 (unregistered) in reply to snoofle
    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 (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
  • /
    • make: *** No rule to make target `programmer'. Stop.
  • Anon (unregistered) in reply to Tony

    1.

    Tony:
    COMMENT ME!

    1. ?
    2. Profit!
  • Hans (unregistered)

    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 (unregistered)

    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 (unregistered) in reply to np
    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 (unregistered)
    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 (unregistered) in reply to Ken B
    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 (unregistered) in reply to anonymouse
    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 (unregistered)
    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 (unregistered) in reply to snoofle
    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 (unregistered) in reply to transverbero
    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 (unregistered)

    53.8% javadoc, that's a lot!

  • imu (unregistered) in reply to Chris
    snoofle:
    /**
 * CREATE SUPREME BEING
 */
    Wouldn't SUPREME BEING be a singleton?
  • Taka (unregistered)

    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 (unregistered) in reply to Buddy
    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 (unregistered) in reply to Sindri
    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 (unregistered) in reply to Bob
    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 (unregistered) in reply to Bob
    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 (unregistered) 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?
    CVS is a real crude hack...
  • Buddy (unregistered) in reply to OldTechSupport
    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 (unregistered) in reply to Buddy
    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 (unregistered)

    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

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

  • (cs) in reply to snoofle
    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"?
  • (cs) in reply to dkf
    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.
  • (cs)

    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 (unregistered)
    /** * @todo DOCUMENT ME! */
  • zerocon (unregistered) in reply to AnyonymousOrSmthing
    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 (unregistered) in reply to my name is missing
    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

    --

Leave a comment on “Self-Documenting”

Log In or post as a guest

Replying to comment #:

Log Out

« Return to Article