From: David Chelimsky <dchelimsky@...>
Date: 2007-04-25T19:47:19+09:00
Subject: Re: Cards Class

On 4/23/07, Ken Mitchell <kmitchell@farmerswireless.com> wrote:
> As a newcomer, you are in a perfect position to learn how to properly
> document your work.  Not only "proper" in your eyes, but it is so easy
> to make it compatible with rdoc.  For instance:
>
> ##
> #    Has properties resembling that of a deck of cards
> #
> Class Deck
>
>     ##
>     #    Constructs and returns an instance of Deck
>     #
>     def initialize
>         .......
>     end
>
>     ##
>     #    Does some action to an instance of Deck.  Argument foo must be
> of type string.....
>     #
>     def bar(foo=nil)
>         ........
>     end
>
> end
>
> Running this through rdoc will quickly create some helpful results,
> especially as your code grows and you begin to reuse as much as
> possible.

Peter - Agile thinking has some interesting ideas about comments that
you should read up on as well before you dive in and comment every
little thing in your code. Essentially, comments are an additional
maintenance burden (you have to change them when you change your
code), and they become a liability if they stray from reality (which
they often do). While there are definitely times when comments are
useful, there are also times when they add very little or no value, in
which case you should prefer well named classes and methods that tell
their own story.

You can find a plethora of varying opinions about this if you google
"code smell comments".

Cheers,
David