From: John Joyce <dangerwillrobinsondanger@...>
Date: 2007-07-02T15:20:50+09:00
Subject: Re: newby non/programmer trying to understand classes


On Jul 1, 2007, at 12:36 PM, Chad Perrin wrote:

> On Mon, Jul 02, 2007 at 02:25:22AM +0900, John Joyce wrote:
>>
>> Don't document your code for other people,  do it for yourself!!
>> You WILL FORGET what something does!
>
> When you come back to your code later, *you* are a different person.

Perhaps. This is a philosophical joke that could run  in circles
>
>> Especially, when you're new at it.
>> So don't be afraid to over document in the beginning.
>> It takes time to develop a documentation style that is concise but
>> still clear.
>> Eventually, you will document less because Ruby is very readable, but
>> always say what a variable or object is supposed to do, what it
>> recieves, what it returns, and maybe even why.
>
> I take it you don't subscribe to the notion that code should tell us
> "how" and comments should tell us "why", then.
Not necessarily. If somebody is really just starting out, comments  
are notes to self about how and why.