[erlang-questions] Style wars: junk comments

[Ivan Uemlianin]

I agree.

The emacs gen_server skeleton has things like:

%%%===================================================================
%%% API
%%%===================================================================

...

%%%===================================================================
%%% Internal functions
%%%===================================================================

(note 70 chars wide)

It's as if they're section headings at the top of a page in a book.

 >    -section(creating).
 > ...
 > 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.

A section attribute would be perfect.  If required emacs erlang-mode 
could give it a (70 char wide) tastefully coloured highlight.

Ivan


On 12/09/2012 08:56, Richard O'Keefe 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
>


-- 
============================================================
Ivan A. Uemlianin PhD
Llaisdy
Speech Technology Research and Development

                     ivan@REDACTED
                      www.llaisdy.com
                          llaisdy.wordpress.com
               github.com/llaisdy
                      www.linkedin.com/in/ivanuemlianin

               "hilaritas excessum habere nequit"
                  (Spinoza, Ethica, IV, XLII)
============================================================