[erlang-questions] Style wars: junk comments

[Bengt Kleberg]

If you expect your code to be read/reviewed when printed, you should
have the functions alphabetically ordered.
Grouping exported/internal functions also help the reviewers.


bengt

 On Wed, 2012-09-12 at 10:26 +0200, Daniel Eliasson wrote:
> I've seen comments beginning with %%%_* that I believe are used as a
> tag for some kind of text folding mode in Emacs.
> 
> I also don't get why people wouldn't sort their export lists alphabetically.
> 
> On 12 September 2012 09:56, Richard O'Keefe <ok@REDACTED> wrote:
> > I was looking at some Erlang code today,
> > and it had comments like
> >
> >         % Include files
> >         % External exports
> >         % Internal exports
> >         % Macros
> >         % Records
> >         % External functions
> >         % Internal functions
> >
> > only bulked up, and present even when the sections were empty.
> >
> > I take the definition of a "junk comment" to be
> > "a comment that repeats something immediately obvious
> >  from the adjacent code".
> >
> > I can tell
> >   an include because it starts with -include
> >   an export  because it starts with -export
> >   a macro    because it starts with -defined
> >   a record   because it starts with -record
> >   a function because it does not start with -
> > so most of these are technically junk comments.
> >
> > In fact they remind most unpleasantly of COBOL (IDENTIFICATION
> > DIVISION, DATA DIVISION, PROCEDURE DIVISION) and Classic Pascal's
> > rigid (label; const; type; var; procedure; begin) ordering.
> >
> > In fact this ordering strikes me as pernicious in a very very
> > similar way.  Suppose for example I have a sliding window module
> > in which there is
> >
> >   %------------------------
> >   % Purging
> >   %------------------------
> >
> >   purge(Window) -> ...
> >
> > and this function uses a number of helper functions and macros
> > that are not used in other parts of the file.  I want to put
> > them *here*, close by the function(s) needing them, not to rip
> > them away from their context just because some boilerplate comment
> > says so.
> >
> > In fact I had been thinking about proposing a conventional use
> > of an attribute:
> >
> >   -section(creating).
> >   -section(adding).
> >   -section(purging).
> >   -section(testing).
> >   -section(formatting).
> >
> > This is something that is already allowed by Erlang syntax, so there
> > is no actual language change.  The proposal is to use _this_ attribute
> > for _this_ purpose: *semantic* sectioning.
> >
> > Yes, the debt to the Smalltalk 4-pane browser and its "method
> > categories" *is* pretty obvious, isn't it?
> >
> > The function of the -section attribute is to provide something a
> > text editor can set automatic bookmarks from or at least let you
> > search for, that _cannot_ be trivially determined from the source
> > code.
> >
> > Have I missed an important benefit of the rigid syntactic ordering?
> >
> > While I'm at it, why don't other people sort their export lists into
> > alphabetic order?
> >
> > function and its supporte
> >
> > _______________________________________________
> > erlang-questions mailing list
> > erlang-questions@REDACTED
> > http://erlang.org/mailman/listinfo/erlang-questions
> _______________________________________________
> erlang-questions mailing list
> erlang-questions@REDACTED
> http://erlang.org/mailman/listinfo/erlang-questions