“Good code is its own best documentation. As you're about to add a comment, ask yourself, 'How can I improve the code so that this comment isn't needed?' Improve the code and then document it to make it even clearer.” - Steve McConnell

@CodeWisdom Comments are still useful when they answer *why* the code was written, or I'd say designed like that.

@CodeWisdom I agree. Document assumptions, not code.

@CodeWisdom Can be true, but only in very generic algoritms. I always recommend to not comment what you code, but witch problem are solving.

@CodeWisdom I used to believe this. Then I worked with enormous code bases left by people of varying skill. The people who try to practice this usually aren't the ones who are good enough to do it properly. They miss the point that this philosophy still says to make a comment.

@CodeWisdom @AmelieCornelis How do you convey the thought processes that went into choosing that approach in code? How do you convey the decisions not taken and the reasons they should be avoided? Code should have clarity, however it's a snapshot of a thinking process by one or more humans over time.

@CodeWisdom This assumes everyone is mastering the programming language or framework the code uses. This is not true. Comment as always as possible to facilitate the learning of newcomers on the project.

@CodeWisdom @m_j_o_n_e_s I have @m_j_o_n_e_s to thank for instilling this mantra. So simple but so much better than over-zealous commenting.

@CodeWisdom At time you need to find the middle ground between making your code understandable, and hurting efficiency. IMHO, that's when comments come in. :) #Programming #Wisdom

@CodeWisdom Or you could improve the code instead of documenting the improved code instead of commenting it

@CodeWisdom Si supieras español y yo supiera ingles te contestaría!!!!

@CodeWisdom It's a rule for life :)

@CodeWisdom Fundamentally, what do you *think* code is? It's a document passed from a human to a machine. Or from a human to other humans. It is instructions. Why would you have to document that? At precisely the point where code escapes that context. And it does that. Like right now.

@CodeWisdom I prefer executable specs and unit tests to document the *why?* and comments mostly just to prevent *wtf?* from others and myself later.

@CodeWisdom The more I work in the real world, the more I realize that this is a "perfect world" quote. If it takes an hour to do it right, but 10 minutes to do it quick and comment why, then that's the way you gotta go.

@CodeWisdom Si seulement...

@CodeWisdom I was going to say you should have comments anyway, but I guess the end part covers that still, it may bear repeating