Comments are often a code smell. You should always be thinking "how are people going to figure out how to use or update this code effectively?" And when the res

Comments are often a code smell. You should always be thinking "how are people going to figure out how to use or update this code effectively?" And when the response is to add a comment you should first pause and then consider alternatives such as: renaming variables/methods or extracting code/conditions into well-named methods. After you've expended the effort to make the code easier to understand and more "self-documenting" then go back for another pass and ask yourself the same questions, and write comments appropriately. Generally the only comments you'll have left are API level info and documentation of "intent". Explain the inputs and outputs and their formats of every public method (especially for library code) unless it's mindbogglingly obvious through naming. One of the most important other questions you should ask yourself when looking at code is how easy it would be for the comments to disagree with the code itself. That's another code smell, you should minimize the opportunities for that and make it as easy as possible to keep things in sync, keep the verbosity at an appropriate level. When I look at examples of my own code that I think are well documented I see some examples with hardly any comments and some where the comments are much longer than the method bodies. Just like everything else, documentation and commenting are judgment calls, don't just try to conform to a rule, use your knowledge and experience and keep reviewing your code for readability (and code you review for others as well, of course).