[erlang-questions] Style wars: junk comments

Richard O'Keefe <>
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
	% 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




More information about the erlang-questions mailing list