[erlang-questions] Style wars: junk comments

[Daniel Eliasson]

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