51–60 of 198 posts
Earlier quoted context omitted.
> Personally I have no problems with comments in code for complex functions etc I hope you have a problem with complex functions. (They should be made as simple as possible).
Why fear complexity when its the only way to get something done, other than not doing it?
Earlier quoted context omitted.
No comments are better than bad comments. There is nothing worse than a misleading description.
I've always gone with the adage: if the comment and code do not agree, don't assume that either of them are correct. A bad description isn't just a problem in itself, it can indicate a worse problem sat waiting to jump out and bite as you walk by.
Comments say what your code does, your code says how you do it. The swap example is trivial, but for most functions it is good to add an API comment, because how you use the function shouldn't depend on how it's implemented, but what it should do, described in the comment. That way you can change your implementation as long as you don't change the contract. In other words, changing how your code does something should…
I was always told that if someone couldn't tell what your code was doing by glancing at it, you'd done it wrong and should re-write it. I know that's absurd in practice, we don't always have the time but I've always used comments as a last resort. If I need to comment code to make it understandable at a glance, so be it but I'd rather avoid them all together and rewrite until it's clear enough without them.
I shouldn't have to read code in detail to understand it, unless it is broken and I am fixing it. Comments should inform me on the broad strokes of the code.
- The proper use of comments is to compensate for our failure to express ourself in code. Comments are always failures. We must have them because we cannot always figure out how to express ourselves without them, but their use is not a cause for celebration. So when you find yourself in a position where you need to write a comment, think it through and see whether there isn’t some way to turn the tables and express yourself in code.
- The older a comment is, and the farther away it is from the code it describes, the more likely it is to be just plain wrong. The reason is simple. Programmers can’t realistically maintain them.
- Comments Do Not Make Up for Bad Code! One of the more common motivations for writing comments is bad code. We write a module and we know it is confusing and disorganized. We know it’s a mess. So we say to ourselves, “Ooh, I’d better comment that!” No! You’d better clean it! Clear and expressive code with few comments is far superior to cluttered and complex code with lots of comments. Rather than spend your time writing the comments that explain the mess you’ve made, spend it cleaning that mess.
``` // Bad:
// Check to see if the employee is eligible for full benefits
if ((employee.flags & HOURLY_FLAG) &&
(employee.age > 65))
// Good:
if (employee.isEligibleForFullBenefits())I've always treated comments as code smells. Not necessarily something bad, but something that at least suggests the possibility of suboptimal code. One of the best cases for comments IMO is documenting an unexpected behaviour on the part of a third-party API. But even then, correct exception / error-handling code can obviate the need for comments in many cases. If I'm reading code (from an experienced programmer) an…
Earlier quoted context omitted.
Why fear complexity when its the only way to get something done, other than not doing it?
There is no such complex function that can't be decomposed to bunch of simple(r) functions.
Earlier quoted context omitted.
I've always gone with the adage: if the comment and code do not agree, don't assume that either of them are correct. A bad description isn't just a problem in itself, it can indicate a worse problem sat waiting to jump out and bite as you walk by.
comments might diverge from behaviour but the code, almost by definition (modulo some crazy magic happening/broken interpreter ) _is_ the behaviour.