[Tutor] commenting code well

[Allan Crooks]

Rob,

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

As well as the useful advice given here, I also tend to put comments where I have created one solution for a function and then rewritten it due to some bug / inefficiency. I explain in the code why it is doing it this way, and perhaps why not in a more obvious way.

And I have in the past come across sections of my code and thought "why don't I improve it by doing it this way", and the comments have prevented me making the same mistake.

Before Python, I used to code in Java a lot, and I obeyed the Javadoc convention. But for methods which were simple get / set methods, this used to be overkill, since they didn't really need comments, they were self-explanatory. So any comment things if they are of any use. It helps if you attempt to document it for someone who has no real idea what the code does (i.e. miss out the obvious things, explain the not-so-apparent things)

For docstrings of functions, I'd document what it does, and document any behaviour that may not be readily apparent (e.g. raising an exception if a certain combination of parameters are provided).

I'd have to agree that the freshmeat article is fairly useful, so I would look at that. :)

Allan.