On 10/11/06, Tom Armitage <tom.armitage / gmail.com> wrote:
> On 07/10/06, Kevin Olemoh <darkintent / gmail.com> wrote:
> > With respect to copious amounts of comments what makes it a good idea
> > to assume that whoever else might be reading the code you have written
> > is at the same skill level as you are especially if you decide to
> > opensource your work.
> [snip]
> > Eg:Case
> > statements alot of the people I know at Uni don't really understand
> > cases so I try to put comments near my cases if I am going to be
> > sharing code with them.  Or I simply tell them what this or that does
> > while I am face to face with them.
>
> I want to go back to this.
>
> Comments aren't to do with bringing people up to a skill level.
> Comments are to do with explaining things that anyone of a reasonable
> skill level couldn't work out.

Hear, hear!

There are are also dangers to overcommenting.

Some years ago Gerry Weinberg wrote the classic "Psychology of
Computer Programming" and he talked about this.

One danger is that you can fall into the trap of debugging the
comments rather than the code when something doesn't work.  The
comments are really only the authors *opinion* of what the code is
supposed to be doing.  If you can't write clear code, and rely on
comments to 'explain' your thinking, you, or someone who comes after
you, can be tricked into thinking that the comments are accurate, and
miss what's really happening when the code and the comments don't
agree.

Weinberg went so far as to suggest that a useful tool would be one
which stripped source code of all comments.

If the guys you are sharing code with don't understand the language,
either teach them or give them a book on the language.

-- 
Rick DeNatale

My blog on Ruby
http://talklikeaduck.denhaven2.com/