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

>
> PS: No matter how you end up writing code, I believe its very  
> important
> to
> provide docu which EXPLAINS to others what you were doing. Especially
> sometimes I end up seeing code of other people which is really hard to
> understand, not so much because I dont understand everything (i still
> learn a lot of new things) but more so because they do it IMHO in a
> complex manner ... this is hard to understand sometimes.
>

Don't document your code for other people,  do it for yourself!!
You WILL FORGET what something does!
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.
Same for functions or code blocks. Refactoring code, basically  
creating functions and blocks and classes that compartmentalize/ 
modularize code, is very good for you and for your code, but after it  
grows, it will become harder to put it all together mentally.