3 ms·

Put the comments above the routine, and try to keep the routine statements/expression/code to about one screenful of code (give or take, needs vary). Make the

• bborud 15y ago
  This depends a bit on the type of comment. If we are speaking Java or something that uses the method comment to generate documentation, the documentation comment should not concern itself with implementation detail. However, documenting all pre- and post conditions as well as any side-effects is a good thing. (It is important to know when you are documenting the API and when you are saying something about the underlying implementation -- and what you should say. Again, the goal is to anticipate what will help your users or maintainers that come after you do the right thing). Occasionally you will need to make some comments regarding the implementation, and I usually make those comments at the start of a code paragraph. Usually to clarify intent when the intent can be misunderstood (to counter "I know what the code does, but not what it tries to accomplish"). Keeping methods short is a good thing, but I'm not dogmatic about it. Though I am allergic to long methods; occasionally there are methods that become even harder to read if you chop them up into lots of small bits. In that case guard-based programming and making use of paragraphs in your code really does help.