[erlang-questions] Style wars: junk comments
Wed Sep 12 09:56:19 CEST 2012
I was looking at some Erlang code today,
and it had comments like
% Include files
% External exports
% Internal exports
% 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
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
In fact I had been thinking about proposing a conventional use
of an attribute:
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
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
function and its supporte
More information about the erlang-questions