On: Reasons to avoid code comments

[radicalbyte]

The example given as reason #5 just goes to highlight the original author's ignorance.

  /**
  * 
  * @param title The title of the CD
  * @param author The author of the CD
  * @param tracks The number of tracks on the CD
  * @param durationInMinutes The duration of the CD in minutes
  */

Is a format used for tooling support, it's NOT "just a style".

Java & C# both provide format for XML comments, which are then used to generate API documentation and to improve auto-complete.

With these comments, a user of the function doesn't need to read through the source code to understand what it does.

A quick google shows that these tools exist for Javascript:

http://stackoverflow.com/questions/9263005/javascript-docume...

http://yui.github.io/yuidoc/

I'm sure that the fulltime javascripters here could post better examples and tooling support..

[seanmcdirmid → radicalbyte]

Good god, you've brought back nightmares about WPF documentation now. Want to know what XXX property means in WPF? Well, the documentation will helpfully tell you that "gets or sets the XXX property of the FULLNAMESPACE class."

I've learned that sometimes BIGCORP makes developers document something when they have nothing interesting to say.

Someone should design a programming language without commenting capabilities and figure out a new/different/better way to deal with library API documentation problems as well as implementation documentation.

[nknighthb → radicalbyte]

The comment merely duplicates information already present in the function signature.

    public void addCD(String title, String author, int tracks, int durationInMinutes)

It's uninteresting and superfluous. Just like virtually all other Javadoc-style comments I've ever seen.

[ajanuary → nknighthb]

Worse than that, it can get out of step with the method signature. A lot of tools I've seen will take the doc comment as an authority over the method signature, even if they don't match up.

Javadoc-style for documenting method behaviour is quite often very useful for explaining the edge cases and stuff like that. I wish I could just document the parameters that are interesting, and have the tools merge that with the method signature.

[h2s → ajanuary]

Not only are you right that these docblock comments can get out of sync with the real parameters, but I would argue that it is almost inevitable that they will. I rarely waste my time reading them any more, but when I do, there's something out-of-date more often than not.

I like your idea of documenting only the interesting aspects of the parameter list. I'd advocate just going ahead with it, using plain old concise English prose to do so. Comments are supposed to be for humans to read anyway.

[chris_wot → nknighthb]

The title of the author, or the title of the CD? Or perhaps it's a track title?

[nknighthb → chris_wot]

If I encountered anyone actually calling that function and seriously wondering what "title" could refer to, my reaction would be to call an ambulance, because they're clearly in the midst of a stroke.

Comments do not exist to explain basic everyday concepts, nor basic linguistic skills.

You might as well ask "what's a CD?".

[MaulingMonkey → nknighthb]

You assume "addCD" actually adds a CD to, say, a music library, rather than being a butchery of "addToCD". This might be unlikely in Java, but if this were C89 (where no function has a containing class and where no parameter based overloading is possible), I'd be calling you the ambulance if you weren't seriously wondering whether "CD" refers to what's being added to, or what's being added.

[nknighthb → MaulingMonkey]

Bad names are bad code, and comments are not an excuse for bad code.

There's also no reason to believe someone with byzantine naming practices is going to be any better at documentation anyway.

And why would a function for adding to a CD have an integer parameter named "tracks"? (If your next argument is "maybe it's for the track number"... Bad name! Bad code!)

Finally, context is important, and considering a single function in isolation and thinking up all the ways in which it might be ambiguous (though I've yet to see anyone identify a plausible way in which this one could possibly be) is ridiculous. In all likelihood, the behavior of a function is even more obvious in the overall context of the system/API it's part of.

[MaulingMonkey → nknighthb]

And I don't meant to suggest papering over bad naming conventions with comments. You're preaching to the choir there.

What I do mean to suggest is that while in any half decent codebase, addCD should be unambiguous, someone thinking title is ambiguous isn't having a stroke -- at worst they're being incredibly jaded. API design is nontrivial, people make mistakes in the trivial cases distressingly often (due to laziness, lack of familiarity, wildly different backgrounds, or any number of other reasons), and relying on context too much has it's own problems anyways.

For example: We're missing it in the very snippet we're discussing. There's no class shown. You're filling in the blanks with reasonable code. I've seen far too much unreasonable code to dismiss it when talking coding styles, and even reasonable code is only a botched refactoring or two away from being unreasonable.

[ajanuary → chris_wot]

If it's that confusing, rename the parameter.

    public void addCD(String cdTitle, String cdAuthor, int numTracks, int durationInMinutes)

[pauloortins → ajanuary]

Exactly, why write comments if you can choose better names ?

[pauloortins → radicalbyte]

With all the respect in the world, but documentation like that, don't provide any useful information. It only produces noise.