[erlang-questions] Speaking of comments

[Edmond Begumisa]

On Mon, 13 Dec 2010 19:34:36 +1100, Banibrata Dutta  
<banibrata.dutta@REDACTED> wrote:

> On Wed, Dec 8, 2010 at 8:45 PM, Edmond Begumisa  
> <ebegumisa@REDACTED
>> wrote:
>
>> I've thought -- now and then, in the back of my mind -- about removing
>> comments from actual source all-together (for all languages) and  
>> instead,
>> putting them in companion files that the editor lines up side-by-side.  
>> More
>> like annotating than just traditional commenting.
>>
>>
> It's an interesting thought, as it removes clutter -- especially so for a
> programmer who is already well versed with the code.

I agree. I've frequently wanted to add more running commentary on a piece  
of code then stopped myself because of the verboseness it would introduce.  
It would be nice to be able to add comments "on the side" without  
affecting the readability/compactness of a function, especially for a  
language as terse as Erlang. It would also be nice to be able to do this  
with headings-body, nesting/depths and user-name tags (like comments on a  
blog) plus richness of content (e.g. many times I've wished I could stick  
a PNG diagram from some spec into a comment.)

Treating annotations and source-code as two different (but related) things  
might be the answer.

> Most modern editors have features allowing the view to show all comments
> collapsed, expanded, and some even done so selectively.
>

Exactly! This is the concept I would like to see expanded on. Collapsible  
annotation. But as pointed out in that article Toby posted, were not  
making much use of the space to the right of our editors. That seems like  
the perfect place to display comments (of the commentary variety), and  
offers potential for some flexibility (e.g. more than one comment could be  
placed next to a single line or chunk of code like next to the function  
name - hovering the mouse over each heading could then show the detail.)

I also don't like that many editors force me to think about wrapping when  
writing English comments (writing English is not the same as writing  
code). With the editor split into two panes, code on one side, rich  
English/Swedish/Hindi/Chinese/Arabic on the other, different wrapping +  
rtl/ltr could be used.

>
>> Has this sort of thing been done before? Is there a particular editor  
>> that
>> can give me this out of the box? (I admittedly haven't explored a large
>> number of editors)
>>
>> Using Erlang as an example, I've secretly wanted something like...
>>
>> foo.erl
>> foo.cts
>>
>
> Challenge would be to ensure 100% (fail-proof) lock-step update of the  
> .erl
> and .cts files in VCS... ideally triggered from a single command.
>

True. As a VCS user, you'd generally have start thinking of each file as  
two files.

>
>> Then an editor that could give me two panes while keeping the two files  
>> in
>> sync...
>>
>> foo ->  | This function does...
>>  blah  |   This part is buggy...
>>  balh  |
>>
>> Also, in the right pane, I've wanted nestable trees with flexible  
>> levels of
>> detail. Heck, why not even rich text? "FIX ME" in bold red. Take it  
>> further:
>> login-name awareness, source-control/bug-tracker integration (this
>> programmer said this, that programmer said that.)
>>
>> It seems a shame that in 2010, it's still so limiting what we can do  
>> with
>> comments in our source code!
>>
>> - Edmond -
>>
>> On Thu, 09 Dec 2010 01:39:42 +1100, David Mercer <dmercer@REDACTED>
>> wrote:
>>
>>  On Tuesday, December 07, 2010, Richard O'Keefe wrote:
>>>
>>>  Nesting comments are one of those clever ideas
>>>> that turn out to be really dumb, because they don't actually work.
>>>>
>>>
>>> I'll bite, mainly because I've sometimes thought nesting comments  
>>> would be
>>> helpful, for instance, when commenting out large blocks of code, but  
>>> it is
>>> rare that I get to work with a language that supports them.  Since  
>>> you're
>>> almost always right about such things, why do you say that they don't
>>> actually work?
>>>
>>> Cheers,
>>>
>>> David
>>>
>>>
>>>


-- 
Using Opera's revolutionary e-mail client: http://www.opera.com/mail/