[erlang-questions] Style wars: junk comments

Wed Sep 12 12:10:20 CEST 2012

> 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
      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.

More information about the erlang-questions mailing list