CodeSOD: True if Documented

This post was originally published on this site

The Daily WTF

“Comments are important,” is one of those good rules that often gets misapplied. No one wants to see a method called addOneToSet and a comment that tells us Adds one item to the set.

Still, a lot of our IDEs and other tooling encourage these kinds of comments. You drop a /// or /* before a method or member, and you get an autostubbed out comment that gives you a passable, if useless, comment.

Scott Curtis thinks that is where this particular comment originated, but over time it decayed into incoherent nonsense:

///<summary> True to use quote value </summary> /// ///<value> True if false, false if not </value> private readonly bool _mUseQuoteValue

True if false, false if not. Or, worded a little differently, documentation makes code less clear, clearer if not.

[Advertisement] Otter – Provision your servers automatically without ever needing to log-in to a command prompt.

To read the full article click on the 'post' link at the top.