3 ms·

I don't think every function needs a comment, necessarily, but I have seen "self-documenting" used as an excuse for not documenting anything at all. It's easy t

• j_baker 16y ago
  Fair enough, but that's kind of orthogonal to the author's point isn't it? An idea isn't wrong just because it can be abused.
• dwc 16y ago
  I've also seen that used as an excuse, along with almost everything else you can think of. We've all seen the results of "I'm adhering to each and every rule but coding how I want anyway" coders.
• rnemo 16y ago
  Agreed. While the author tends to take the viewpoint that attempting to write self documenting code is almost a bad thing, and that's very wrong, I understand his frustration, because too many programmers these days seem to think that documentation in the comments are either superfluous or a sign of bad code, and that's also just flat wrong. It's a shame that the author takes the opposite extreme. Like most things in life, code documentation requires balance, and one should strive to create code that is easy to read and understand, but good code cannot be easy to read and understand in all circumstances, and comments should be used in any situation that confusion could possibly arise. For my own code, aside from commenting on obviously confusing sections, I tend to create functions that have an easily understood purpose when called, but I tend to use 1-2 lines of comments when I declare the function so that I can feel reasonably sure that anyone reading my code wont have too many questions. I've found through feedback that this is a fairly functional method of documentation.