Marcel Ward wrote:
I see it as an opportunity to document my thoughts in solving the
quiz, and thereby teach myself and others. The best way to learn is
to teach.
I can't disagree with that - it's been my theory up until now but I
have no idea how useful it's been to others. If I'm just turning
people away with long posts then I'd prefer to shorten them down to
meet the audience's expectations better.
I say: go for long emails if you have to, but try to be as precise as you can. This has the "learning through teaching" effect, and helps to keep your emails at a manageable length.
It is my opinion, that those, who can't be bothered to read a long explanation, won't read the documentation either, which results in somebody who can't be educated in the first place.
Rest assured, if the topic interests me, I'll read a long email, too.
I'm definitely in favour of comments and readability. I guess I was
just verbalising some inner thoughts and wondering how others try to
find the right balance.
Well, if the code is readable and speaks for itself, comments can be omitted. Otherwise, the comments should explain what the code does, not what it should do.
I.e.:
#Opening a file
f = File.open("foo")
^
is superfluous.
#This does stuff to the passed argument bar
def do_stuff(bar)
#doing stuff to bar
end
^
Isn't superfluous, and aids debugging if the thing doesn't do what it should. And you know that it doesn't do what it is supposed to do, because your tests tell you that it doesn't.
But such a thing merits it's own thread, I'd say.
···
--
Phillip "CynicalRyan" Gawlowski
http://cynicalryan.110mb.com/
Rule of Open-Source Programming #8:
Open-Source is not a panacea.