[Tutor] commenting code well

[Roeland Rengelink]

Rob Andrews wrote:
> 
> My code comments are often weak, if existent. What is good practice for
> commenting code?
> 

Well, not having (many) comments in your code may actually be what you
should aim for. I try to use comments only for:

1. Explaining non-obvious algorithms
2. Notes to myself, usually of the form  '# XXX Improve this'

The ultimate goal is of course to remove these (yes, 1 too)...

The most important rules of comments are:

1. Bad or inconsistent comments are worse than no comments at all.
2. Redundant comments are redundant.

And, specific to Python:

3. Comments are for programmers, put info for users in doc strings.

I use the following 'tricks' to avoid writing comments.

- use descriptive names for variables, functions, etc.
- try not to be clever, do the obvious thing
- write good doc-strings

Now, my problem is writing good doc strings...

Roeland
-- 
r.b.rigilink@chello.nl

"Half of what I say is nonsense. Unfortunately I don't know which half"