From: James Britt <james_b@...>
Date: 2006-05-16T13:21:09+09:00
Subject: Re: Ruby & Emacs

Eric Armstrong wrote:
> Similar, but with an important difference. The user
> guide tells someone how to use the program to do what
> they need to do. It's necessarily use-case oriented.
> 
> Comments tend to be implementation-oriented. They
> tell how the /program/ does what it does. 

Well, comments that just describe what the code is doing aren't always 
helpful. I tend toward comments that explain the purpose and rationale 
for the code.  The code itself should be clear enough to describe what 
it is doing.

Yes, they are always user-centric.  But they do often have a "thinking 
out loud" quality which is handy when writing up user docs.

The comments are often user stories that are then transmogrified into 
tests and code to make the stories live.


-- 
James Britt

"In Ruby, no one cares who your parents were, all they care
  about is if you know  what you are talking about."
   - Logan Capaldo