From: Tom Armitage Date: 2006-10-11T18:39:52+09:00 Subject: Re: What is the reason for this syntax? On 07/10/06, Kevin Olemoh 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.