Re:Reasons to avoid code comments
by mbrock on Saturday July 13, 2013 @06:07AM
(#6037189)
In systems grown over many years and by many developers, comments about such things are nearly worthless, because they can't be trusted. I wouldn't be surprised to see a comment saying "title cannot be null" right above code that explicitly permits null. A comment that lists which exceptions can be thrown is highly suspect, I would probably delete that just to avoid confusion, and make sure that it's obvious from the code instead.
[ Parent
| on HN ]
Re:Reasons to avoid code comments
by MaulingMonkey on Saturday July 13, 2013 @08:13AM
(#6037374)
When code has been poorly refactored (I'd count "documentation/comments weren't updated") I find knowing the original intent behind classes and methods to be useful in understanding their mutated design, and how it was arrived at.
Further, handling of the edge cases may have changed, but many of those changes may be bugs in the code to be fixed rather than intentional design changes to be re-documented. When fishing for the cause of a crash, said comment can help verify the existence of a bug, even if it's not the bug you're looking into.
They can also guide the fixing of that bug. This variable shouldn't be null: is that the fault of the callee for not providing a fallback? the caller for violating function preconditions? caller of caller for the same? another class that had it's invariants violated without asserting?
Re:Reasons to avoid code comments
by ExpiredLink on Saturday July 13, 2013 @07:45AM
(#6037329)
> comments about such things are nearly worthless
The Java ecosystem lives on such comments. I wouldn't use a Java API without "Javadoc" documentation.