How to comment code?

Martin P. Hellwig mhellwig at xs4all.nl
Fri Jan 19 16:31:27 EST 2007


Hi all,

I've been toying with python for about two years now. Not every day, 
just when I encounter something in my job (sysadmin) repetitively dull.
The amazing thing is that like any other language (natural or not) 
learning it more gives you power to express your thoughts better and 
create something from nothing, for me this is something I can only 
compare to freedom.

However since I'm learning more of python I've struggled with 
commenting, how should I've comment my code? I'm not talking about the 
style but more on the concept itself, things that where a couple of 
month ago a bunch of monkey poop is now as easy as reading a comic.

I always give a brief description on what the code is supposed to do and 
  I suppose that any serious coder knows way more then me about 
programming so I don't bother to comment that much since it mostly (in 
my eyes) just clutters up the code and makes it actually harder to read.

Though this makes me uncomfortably, commenting so little, I was thinking 
that perhaps something like doctest (I'm not so much into unit testing 
or the equivalents at this moment) has the side affect to make my code 
more understandable and readable. Any practical experience you'd like to 
share with me, any other comments are welcome too of course :-)

Thanks.

-- 
mph



More information about the Python-list mailing list