Re: Problems retaining what I study

On 19/08/05, Sarah Satterthwaite <ssatterthwaite_at_cswcasa.com> wrote:
> When documenting your code, be sure to also document your doubts about how
> you did it. I find that most of the bugs that are found in my code are
> things I wasn't very confident about at the time! It sure is easier to find
> the bug when there are pointers to the likely bugs :)

True, very true.

I normally get about a 7 to 1 code to comment ratio. For example if I write a function there's a chunk of comment at the top which explains what it does, what parameter is takes and what outputs it produces along with all errors/exceptions it's likely to raise and suggestions as to how the calling function might like to respond to that. Most actual lines of code will have a comment next to them explaining what they do

I'd rather spend 20 minutes now writing an explanation of what something does than spend 5 hours in a year's time trying to work out what it does, before giving up and rewriting it from scratch.

Stephen

-- 
It's better to ask a silly question than to make a silly assumption.
--
http://www.freelists.org/webpage/oracle-l