[erlang-questions] Style wars: junk comments

[Richard O'Keefe]

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