|
|
|
|
|
|
by strommen
3935 days ago
|
|
|
There are definitely cases where comments are required to describe intent...the "Why?" of the code. But the problem with comments is that they'll inevitably get out of sync with the code. And a wrong comment is far worse than no comment at all. In a case like Colin's, I think something as simple as including "secure" or "secret" in the name of the variable would prevent this stuff from happening. If your variable is named `secureAccountCode` then it's unlikely you'll be silly enough to render it back to a hidden input (unless you're writing code comments for "Drunk Me" like the Disqus commenter on the article, in which case all bets are off). There's a classic Joel on Software article about this, "Making Wrong Code Look Wrong" [1] [1] http://www.joelonsoftware.com/articles/Wrong.html |
|
|
Eek, then by all means take comments seriously and change them when your code changes. I think it's particularly important to comment functions and methods (especially effectful/stateful ones) with what precisely they're expected to do, what invariants hold, etc. (insofar as the type system and function name don't make these clear). Otherwise another programmer has no way (aside from looking at and completely understanding every call site) of knowing what bits of the functionality are incidental vs intended behavior, and are likely to make small modifications for their own purposes which break other things.
Programmers seem very eager to lack of comments and I'm super unsympathetic; this is the one thing that just kills me. Comments hold together a codebase, make it much easier to learn and read, and are a way for programmers to impart all sorts of bits of knowledge about the domain that is valuable "we would do X here but foo() from library Y works in such and such a way so, blah blah blah". And if you don't like to read comments like that I'm sure your editor will fold them for you.