From: Phillip Gawlowski <cmdjackryan@...>
Date: 2007-04-10T02:20:48+09:00
Subject: Re: Getting to 100 (#119)

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.