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.

I'm not a fulltime programmer, and I don't have a CS degree. But I
work in Ruby quite a lot. I've seen quite a bit I don't understand -
in opensource and internal projects - and I've either *worked it out*
or *asked somebody*.

So: case statements are a classic example. I don't think it's
unreasonable to assume a half-skilled programmer would get a case
statement. But even if they don't, because they've used some evil
language without them forever, I expect them *to be able to use
Google*. (Similarly: I'd expect a Ruby programmer to know certain
idioms, even if they don't use them themselves).

Here we go: Ruby case expressions, straight from the pickaxe:
http://whytheluckystiff.net/ruby/pickaxe/html/tut_expressions.html#S5

If the first line: "The Ruby case expression is a powerful beast: a
multiway if on steroids." doesn't make things blindingly clear, the
two examples do. If you don't know about Ruby's case statements...
well, now you do! Wow!

There's a difference between "reasonable" syntax (stuff I use that you
may not use, but you can understand) and "unreasonable" syntax
(hideously obfuscated one-liners, I'm looking at you, Perl).

Comments aren't to explain things in the langauge someone might not
understand. They're to explain things in your program; WHY you do a db
write everytime someone logs in; HOW the API to the other server
should be implemented; WHAT the reasons behind a chunk of code are.
They're not to educate the other programmer.

There's been a lot of "real world" talk. In the real world, comments
are almost never for things "that might be a bit strange to someone
not because of formatting but because they simply have never seen a
given technique I use before". They are often for documenting which
technique you've used - for instance, how I document CSS hacks - but
that's as much for yourself as for other people. It's not about
education. There are other resources for that.

And, as a hacky programmer with no formal training, I say that having
used those other resources copiously.