From: Eric Armstrong <Eric.Armstrong@...>
Date: 2006-05-18T08:36:59+09:00
Subject: Re: Ruby & Emacs

Ah ha. VERY nice. I see the integration now.

James Britt wrote:
> 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.
> 
>