[erlang-questions] Style wars: junk comments

[Bengt Kleberg]

Just in case that semantic categories means that functions that belong
together are placed together, I solve that kind of problem by having the
same prefix on functions that deal with the same thing.


bengt

On Wed, 2012-09-12 at 12:10 +0200, ok@REDACTED wrote:
> > I can understand that if you know what you're looking for (and just want
> > to check, say, function signature), then the alphabetic ordering may help.
> > However, if one wants to find out what is particular module
> > doing/responsible for, I would really like to learn how can alphabetic
> > ordering help.
> 
> Just to make it clear, I was advocating that the list of
> function names in an -export directive should be sorted,
> while the function definitions should be grouped into
> semantic categories.
> 
> Two historic comparisons:
>  * the Burroughs Extended Algol compiler had a long list
>    of forward procedure declarations near the front, each
>    with an associated sequence number.  Then the actual
>    procedure definitions were grouped semantically.  One
>    typically kept a couple of punched cards stuck in the
>    six-inch listing as bookmarks, one or more of them in
>    the index.  You could find your way around in this
>    huge listing with astonishing ease.
>  * the Smalltalk 5-pane browser (yes, I know I said 4-pane
>    in a previous essage, but I'm typing with a laptop on
>    my chest and am not catching all my typos).
>    Top, left to right:
>       class categories (think 'applications'), alphabetically
>       classes within current category, alphabetically
>       method categories within class (semantic sections), alphabetically
>       methods within category, alphabetically
>    Bottom:
>       Edit window for class definition, class comment,
>       or method definition.
>    Add in the 'find definition' 'find callers' and other
>    single keystroke operations, and you can really *fly*
>    in that interface.  Oh, guess what?  No junk comments!
> 
> If you want to find out what a module is doing or responsible
> for, you should be reading the module comment, not looking at
> the functions.  And there should BE one that TELLS you.
> 
> Note that if you have semantic -sections, then
> 
> egrep '^-(module|section)' foobar.erl
> 
> would tell you quite a bit about what the module is up to.
> 
>