| Sounds like the developers who wrote that code didn't know how to write comments. Here's some guidelines: * Anything that duplicates the line they describe in prose should absolutely be removed. They're worthless and become out of date immediately. * If you have logical "paragraphs" of code separated by newlines and comments summarizing the paragraph, that's a great indication that your parent method/function/whatever is in charge of doing too much. Turn the comments into names of new methods/functions and refactor accordingly. * If the algorithm is sufficiently complicated, it definitely deserves a documentation block describing the "how"s and "what"s. But more often than not those comments are just a duplication, as specified in the first bullet point above. If you don't think any code ever deserves these sorts of comments: congratulations, you've never worked on anything non-trivial in your career. I suggest that you find more of a challenging project. * Definitely leave a comment behind explaining the "why"s behind a particular block of code if its intentions are not immediately obvious. * Definitely have headers of documenting comments for functions/classes/methods/parameters/etc. Is your first reply when someone asks "How do I learn to use Rails?" to say "Read the entire source code to Rails"? No, of course not. For the same reason, your reaction to "How do I use this block of code" should not be "Read the block of code." Abstractions and proper APIs people, come on. I should be able to glance at the docs above it along with the definition and know how to use it, what to pass to it, and what I might expect in terms of returns / side effects. Bonus points if you have a tool to auto-extract these into a static site that you host for your team. |