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 <[EMAIL PROTECTED]> 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.
-Yoda
Try 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
