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?
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?