[erlang-questions] Style wars: junk comments

[ok@REDACTED]

> On 12 September 2012 15:56, Richard O'Keefe <ok@REDACTED> wrote:
>
>>         % Include files
>>         % External exports
>>         % Internal exports
>>         % Macros
>>         % Records
>>         % External functions
>>         % Internal functions
>>
>> only bulked up, and present even when the sections were empty.
>>
>
> …
>
>
>> 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 -
>
> Can you tell this while quickly scanning over the code?

(A) Yes of course I can.  It's right at the xxxxing left margin!
It's the very easiest most obvious place to find stuff.

(B) I have no *reason* to because it is nothing I find useful
to know.

> Can you tell this
> while page-flipping like a madman in your text editor because you're
> looking for a particular section of your code?

I have *NEVER*, not in nearly 40 years of programming,
found it useful to "go where the macros are".
Putting all your macros in front of all your functions
makes about as much sense as putting all the nouns in
your sentences ahead of all the verbs and adjectives.

>From time to time I try to tell people that COBOL
isn't all that bad, and then I remember my intense
frustration at being unable to place data near the
paragraphs that needed them.  Syntactic sectioning
(put all the files in one place, put all the variables
in another place, put all the code in a third place)
did not *solve* the page flipping problem, it *caused*
the page flipping problem.  I actually have a free
COBOL compiler on my machine, and for this reason
above all others, have never been able to bring myself
to use it.

Indeed, this has driven me to wonder whether Ada-style
'child' modules (which are very different from Java-style
'packages') might be a good thing in Erlang.  Haskell
programmers seem to use semantic sectioning in cutting
modules into lots of submodules, although I feel they
take it to an extreme which also hurts readability.

Over and over and over again I have found it amazingly
useful to use SEMANTIC sectioning.  In C code, for example,
I actively and positively want NOT to know whether
attribute_name() -- to take an example from my DVM2 library
for handing XML in C -- is a macro or an exported function
or an internal function, but I want very much to "find
the stuff that handles attributes", and I want to find it
*there* whichever of the three it is.

In any case, you may find it hard to believe, but it is
literally true that when I stripped the junk comments out
of the code I was looking at, the page count of nearly
all the files halved.  Junk comments don't *solve* the
page flipping problem, they *exacerbate* it.

>
> The "bulked up" section that you omitted is, if I guess correctly,
> something like this:
>
> %==================================================

It includes but is not limited to such things, yes.
>
> And the fact, if I'm correct, that you think of this as "bulking up" is
> you
> gloriously missing the entire *point* of heading-style comments: they help
> you quickly locate particular sections of code, or particular functions or
> whatnot by calling attention to themselves.

No, they don't.
* They really do not help me find anything when
using a text editor.  If I *did* want to search for
one of these sections, I'd be searching for '%   Includes',
not for '==='.
* When looking at a printed listing, they don't help
nearly as much as a page break, they only need one line
of fat dashes, not two or more, and they don't help nearly
as much as an Interlisp technique I'll return to
* I was not talking about function headers, not one word
about those.  I have nothing against devices that help me
find particular functions.  However, even then there's
something much better than lines of dashes, the Interlisp
thing I'll get back to.
* The most important point is that these bulked out junk
comments I'm talking about are utterly useless for locating
particular sections of code, quickly or otherwise, because
of their content.  They are SYNTACTIC sections, which
cleave asunder that which should be kept together and
unnaturally conjoin that which should be kept apart.
The includes, types, macros, exported functions, and
internal functions that work tightly coupled to achieve
a particular task are scattered across many syntactic
sections.  Unrelated functions are placed together merely
because none of them are exported.

If someone wants to mark *SEMANTIC* sections up with
bulked out comments, fair play to them, it's not me that
will complain.  Indeed, I'll say "thank'ee kindly."

OK, what did Interlisp do?

When you asked Interlisp to make a listing of a file,
it understood which functions and macros defined things,
and where the name being defined could be found.  So it
displayed those names in a larger font.  Looking at an
Interlisp listing, you could see which functions were
defined where from the other side of the table.

> code to maintain that has no such navigation aids, I grit my teeth, say a
> few very unpleasant things about the parentage of the person who wrote it
> under my breath and then spend the next little while adding those
> navigation aids myself.

Imagine "navigation aids" in the form of signposts
that say things like "signpost", "a street somewhere",
"here", "these are letters".  That's the kind of
junk comment "navigation aid" I am complaining about.