On Dec 8, 2007, at 6:06 AM, Chris Smith wrote:
I usually write out my comments first because it lets me define what I'm trying to do. The code should be a reflection of the comments.On 08/12/2007, Greg Ewing <greg.ewing@xxxxxxxxxxxxxxxx> wrote: Ian Mallett wrote: > When writing code, it is good to have comments, but it is not usually> wise to put them in until you've tested the relevant code. Although sometimes it can be helpful to write a comment beforehand as a sort of mini design document, to help clarify your thoughts about what the code needs to accomplish and how you intend to go about it. If you later change the code in a way that invalidates the comment, you should of course update the comment to match. -- Greg
Comments do not good code make. -YodaTry to write code that makes it easy to see what and how things are being done. Use meaningful, descriptive variable, method and class names. Write the code as though someone else will need to read it and understand it -- 6 months from now that someone may be you. Be explicit, try not to rely-on magical side-effects. Don't optimize code for speed unless it needs it (proven via profiling) since optimization almost always makes code less readable/maintainable.
In general, do not write comments that describe *what* the code is doing, let the code be self explanatory. Write comments that describe *why* the code is there doing what it does. Document the intended usage of methods and classes in docstrings. In all, keep comments to a minimum and worry more about writing clear readable code.
-Casey