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
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:
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?
> 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
> 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:
> 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?
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.
> 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
> 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:
> 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?
"hilaritas excessum habere nequit"
(Spinoza, Ethica, IV, XLII)
============================================================
_______________________________________________
erlang-questions mailing list
erlang-questi...@erlang.org
http://erlang.org/mailman/listinfo/erlang-questions
If you expect your code to be read/reviewed when printed, you should
have the functions alphabetically ordered.
Grouping exported/internal functions also help the reviewers.
bengt
On Wed, 2012-09-12 at 10:26 +0200, Daniel Eliasson wrote:
> > 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
> > 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:
> > 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?
> 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 -<http://erlang.org/mailman/listinfo/erlang-questions>
Can you tell this while quickly scanning over the code? 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?
The "bulked up" section that you omitted is, if I guess correctly,
something like this:
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. Personally, when I'm handed
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.
-- "Perhaps people don't believe this, but throughout all of the discussions
of entering China our focus has really been what's best for the Chinese
people. It's not been about our revenue or profit or whatnot."
--Sergey Brin, demonstrating the emptiness of the "don't be evil" mantra.
"hilaritas excessum habere nequit"
(Spinoza, Ethica, IV, XLII)
============================================================
_______________________________________________
erlang-questions mailing list
erlang-questi...@erlang.org
http://erlang.org/mailman/listinfo/erlang-questions
I can understand that if you know what you're looking for (and just want to check, say, function signature), then the alphabetic ordering may help.
However, if one wants to find out what is particular module doing/responsible for, I would really like to learn how can alphabetic ordering help.
And if this turns to be useful, well, why not go the whole hog and order code alphabetically as well ;-)
> If you expect your code to be read/reviewed when printed, you should
> have the functions alphabetically ordered.
> Grouping exported/internal functions also help the reviewers.
> bengt
> On Wed, 2012-09-12 at 10:26 +0200, Daniel Eliasson wrote:
>> I've seen comments beginning with %%%_* that I believe are used as a
>> tag for some kind of text folding mode in Emacs.
>> I also don't get why people wouldn't sort their export lists alphabetically.
>> On 12 September 2012 09:56, Richard O'Keefe <o...@cs.otago.ac.nz> wrote:
>>> I was looking at some Erlang code today,
>>> and it had comments like
>>> 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
>>> 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:
>>> 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?
If you are reading code on paper, it helps if functions are positioned predictably in the stack of paper. Alphabetic ordering of functions and grouping functions into sections are two good ways of doing this.
> ... if one wants to find out what is particular module
> doing/responsible for, ...
In this case all you should need to do is read the api or exported functions section.
> I can understand that if you know what you're looking for (and just want to check, say, function signature), then the alphabetic ordering may help.
> However, if one wants to find out what is particular module doing/responsible for, I would really like to learn how can alphabetic ordering help.
> And if this turns to be useful, well, why not go the whole hog and order code alphabetically as well ;-)
> V/
> On 12 Sep 2012, at 10:42 AM, Bengt Kleberg wrote:
>> If you expect your code to be read/reviewed when printed, you should
>> have the functions alphabetically ordered.
>> Grouping exported/internal functions also help the reviewers.
>> bengt
>> On Wed, 2012-09-12 at 10:26 +0200, Daniel Eliasson wrote:
>>> I've seen comments beginning with %%%_* that I believe are used as a
>>> tag for some kind of text folding mode in Emacs.
>>> I also don't get why people wouldn't sort their export lists alphabetically.
>>> On 12 September 2012 09:56, Richard O'Keefe <o...@cs.otago.ac.nz> wrote:
>>>> I was looking at some Erlang code today,
>>>> and it had comments like
>>>> 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
>>>> 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:
>>>> 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?
"hilaritas excessum habere nequit"
(Spinoza, Ethica, IV, XLII)
============================================================
_______________________________________________
erlang-questions mailing list
erlang-questi...@erlang.org
http://erlang.org/mailman/listinfo/erlang-questions
When trying to "find out what is particular module doing/responsible
for", on paper, it helps if you can find things. When reading on paper
it is easier to find things when they are alphabetically ordered.
On Wed, 2012-09-12 at 11:00 +0200, Valentin Micic wrote:
> I can understand that if you know what you're looking for (and just want to check, say, function signature), then the alphabetic ordering may help.
> However, if one wants to find out what is particular module doing/responsible for, I would really like to learn how can alphabetic ordering help.
> And if this turns to be useful, well, why not go the whole hog and order code alphabetically as well ;-)
> V/
> On 12 Sep 2012, at 10:42 AM, Bengt Kleberg wrote:
> > If you expect your code to be read/reviewed when printed, you should
> > have the functions alphabetically ordered.
> > Grouping exported/internal functions also help the reviewers.
> > bengt
> > On Wed, 2012-09-12 at 10:26 +0200, Daniel Eliasson wrote:
> >> I've seen comments beginning with %%%_* that I believe are used as a
> >> tag for some kind of text folding mode in Emacs.
> >> I also don't get why people wouldn't sort their export lists alphabetically.
> >> On 12 September 2012 09:56, Richard O'Keefe <o...@cs.otago.ac.nz> wrote:
> >>> I was looking at some Erlang code today,
> >>> and it had comments like
> >>> 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
> >>> 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:
> >>> 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?
Unfortunately, attributes other than -record, -opaque, -type and -spec are forbidden after the first function form. See erl_lint:function_state/2.
Regards,
-- Anthony Ramine
Le 12 sept. 2012 à 09:56, "Richard O'Keefe" <o...@cs.otago.ac.nz> a écrit :
> 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.
> On 09/12/2012 10:33 AM, Ivan Uemlianin wrote:
> Would you prefer 80 chars? Must the IBM punch card still haunt us?! ;-)
You're right. 80 characters is too wide for readability.
We should probably take 72 or 65 as the default.
I would point out that I have actually used an
IBM 96-column keypunch that produced these cute little
96-column cards. Just because it's an IBM punched card
never did mean it's 80 columns. (The really amusing
thing, considering these came from IBM, is that they
used the ASCII code.)
However, it's worth asking why the 80 column card became
a standard, and what the standard actually was.
The actual standard for programming commonly involved an
8 character sequence number on the right (or a differently
sized sequence number on the left for COBOL) so the
*actual* text width was typically 72 characters, which was
rather better for readability.
(I have a colleague who thinks there is nothing wrong with
300-character lines. Needless to say, I have never been
able to read his otherwise superb code.)
On Wed, Sep 12, 2012 at 11:12 AM, Ivan Uemlianin <i...@llaisdy.com> wrote:
> If you are reading code on paper, it helps if functions are positioned
> predictably in the stack of paper. Alphabetic ordering of functions and
> grouping functions into sections are two good ways of doing this.
"Reading code on paper" has already been mentioned some times in this thread.
But really people read code on paper, nowadays?
On Wed, Sep 12, 2012 at 6:12 PM, Ivan Uemlianin <i...@llaisdy.com> wrote:
> If you are reading code on paper, it helps if functions are positioned
> predictably in the stack of paper. [snip]
And COBOL's DIVISIONs made sense when you could get color-coded
pre-punched DIVISION cards in the keypunch rooms, to save time typing
and to help you see, from the top of the deck, which division was
which. Also good back when a COBOL compiler might have five-to-eight
passes, on a machine with 4K instruction space: you could write a
customer parser for each pass.
>> I can understand that if you know what you're looking for (and just want
>> to check, say, function signature), then the alphabetic ordering may help.
>> However, if one wants to find out what is particular module
>> doing/responsible for, I would really like to learn how can alphabetic
>> ordering help.
>> And if this turns to be useful, well, why not go the whole hog and order
>> code alphabetically as well ;-)
>> V/
>> On 12 Sep 2012, at 10:42 AM, Bengt Kleberg wrote:
>>> If you expect your code to be read/reviewed when printed, you should
>>> have the functions alphabetically ordered.
>>> Grouping exported/internal functions also help the reviewers.
>>> bengt
>>> On Wed, 2012-09-12 at 10:26 +0200, Daniel Eliasson wrote:
>>>> I've seen comments beginning with %%%_* that I believe are used as a
>>>> tag for some kind of text folding mode in Emacs.
>>>> I also don't get why people wouldn't sort their export lists
>>>> alphabetically.
>>>> On 12 September 2012 09:56, Richard O'Keefe <o...@cs.otago.ac.nz> wrote:
>>>>> I was looking at some Erlang code today,
>>>>> and it had comments like
>>>>> 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
>>>>> 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:
>>>>> 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?
> "hilaritas excessum habere nequit"
> (Spinoza, Ethica, IV, XLII)
> ============================================================
> _______________________________________________
> erlang-questions mailing list
> erlang-questi...@erlang.org
> http://erlang.org/mailman/listinfo/erlang-questions
-- Regards,
Michael Turner
Project Persephone
1-25-33 Takadanobaba
Shinjuku-ku Tokyo 169-0075
(+81) 90-5203-8682
tur...@projectpersephone.org
http://www.projectpersephone.org/
"Love does not consist in gazing at each other, but in looking outward
together in the same direction." -- Antoine de Saint-Exupéry
_______________________________________________
erlang-questions mailing list
erlang-questi...@erlang.org
http://erlang.org/mailman/listinfo/erlang-questions
> On Wed, Sep 12, 2012 at 11:12 AM, Ivan Uemlianin <i...@llaisdy.com> wrote:
>> If you are reading code on paper, it helps if functions are positioned
>> predictably in the stack of paper. Alphabetic ordering of functions and
>> grouping functions into sections are two good ways of doing this.
> "Reading code on paper" has already been mentioned some times in this thread.
> But really people read code on paper, nowadays?
Yes. Presumably at least the people who have mentioned it already.
It is very easy to underestimate the convenience, reliability, and power of paper and pencil (and perhaps crayons).
Ivan
-- ============================================================
Ivan A. Uemlianin PhD
Llaisdy
Speech Technology Research and Development
"hilaritas excessum habere nequit"
(Spinoza, Ethica, IV, XLII)
============================================================
_______________________________________________
erlang-questions mailing list
erlang-questi...@erlang.org
http://erlang.org/mailman/listinfo/erlang-questions
>> 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.
> When trying to "find out what is particular module doing/responsible
> for", on paper, it helps if you can find things. When reading on paper
> it is easier to find things when they are alphabetically ordered.
> OK? Not OK?
> bengt
> On Wed, 2012-09-12 at 11:00 +0200, Valentin Micic wrote:
>> I can understand that if you know what you're looking for (and just want to check, say, function signature), then the alphabetic ordering may help.
>> However, if one wants to find out what is particular module doing/responsible for, I would really like to learn how can alphabetic ordering help.
>> And if this turns to be useful, well, why not go the whole hog and order code alphabetically as well ;-)
>> V/
>> On 12 Sep 2012, at 10:42 AM, Bengt Kleberg wrote:
>>> If you expect your code to be read/reviewed when printed, you should
>>> have the functions alphabetically ordered.
>>> Grouping exported/internal functions also help the reviewers.
>>> bengt
>>> On Wed, 2012-09-12 at 10:26 +0200, Daniel Eliasson wrote:
>>>> I've seen comments beginning with %%%_* that I believe are used as a
>>>> tag for some kind of text folding mode in Emacs.
>>>> I also don't get why people wouldn't sort their export lists alphabetically.
>>>> On 12 September 2012 09:56, Richard O'Keefe <o...@cs.otago.ac.nz> wrote:
>>>>> I was looking at some Erlang code today,
>>>>> and it had comments like
>>>>> 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
>>>>> 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:
>>>>> 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?
> I can understand that if you know what you're looking for (and just want
> to check, say, function signature), then the alphabetic ordering may help.
> However, if one wants to find out what is particular module
> doing/responsible for, I would really like to learn how can alphabetic
> ordering help.
Just to make it clear, I was advocating that the list of
function names in an -export directive should be sorted,
while the function definitions should be grouped into
semantic categories.
Two historic comparisons:
* the Burroughs Extended Algol compiler had a long list
of forward procedure declarations near the front, each
with an associated sequence number. Then the actual
procedure definitions were grouped semantically. One
typically kept a couple of punched cards stuck in the
six-inch listing as bookmarks, one or more of them in
the index. You could find your way around in this
huge listing with astonishing ease.
* the Smalltalk 5-pane browser (yes, I know I said 4-pane
in a previous essage, but I'm typing with a laptop on
my chest and am not catching all my typos).
Top, left to right:
class categories (think 'applications'), alphabetically
classes within current category, alphabetically
method categories within class (semantic sections), alphabetically
methods within category, alphabetically
Bottom:
Edit window for class definition, class comment,
or method definition.
Add in the 'find definition' 'find callers' and other
single keystroke operations, and you can really *fly*
in that interface. Oh, guess what? No junk comments!
If you want to find out what a module is doing or responsible
for, you should be reading the module comment, not looking at
the functions. And there should BE one that TELLS you.
Note that if you have semantic -sections, then
egrep '^-(module|section)' foobar.erl
would tell you quite a bit about what the module is up to.
>> On 09/12/2012 10:33 AM, Ivan Uemlianin wrote:
>> Would you prefer 80 chars? Must the IBM punch card still haunt us?! ;-)
> You're right. 80 characters is too wide for readability.
> We should probably take 72 or 65 as the default.
> I would point out that I have actually used an
> IBM 96-column keypunch that produced these cute little
> 96-column cards. Just because it's an IBM punched card
> never did mean it's 80 columns. (The really amusing
> thing, considering these came from IBM, is that they
> used the ASCII code.)
> However, it's worth asking why the 80 column card became
> a standard, and what the standard actually was.
> The actual standard for programming commonly involved an
> 8 character sequence number on the right (or a differently
> sized sequence number on the left for COBOL) so the
> *actual* text width was typically 72 characters, which was
> rather better for readability.
> (I have a colleague who thinks there is nothing wrong with
> 300-character lines. Needless to say, I have never been
> able to read his otherwise superb code.)
> On Wed, Sep 12, 2012 at 11:12 AM, Ivan Uemlianin <i...@llaisdy.com> wrote:
>> If you are reading code on paper, it helps if functions are positioned
>> predictably in the stack of paper. Alphabetic ordering of functions and
>> grouping functions into sections are two good ways of doing this.
> "Reading code on paper" has already been mentioned some times in this
> thread.
> But really people read code on paper, nowadays?
Yes, me, lots.
Let me offer you a paradox, half fun and full earnest.'
Fancy text editors and IDEs are tools for NOT reading code.
If you actually want to read code, paper (ideally augmented
with literate-programming-style automatically generated
indices) is way better. If you don't know what I'm talking
about, look at Knuth's "The Stanford GraphBase".
Just today, I found a bug in a Smalltalk class that had
defeated me for a day because using an IDE is too much
like tunnel vision. Given a printed listing, it took me
half an hour to read the whole class, and the bug practically
jumped up and down and shouted to get my attention. (In
fact there were two copies of it.) And another bug that I
hadn't tested for yet also demanded and got my attention;
working with the code in the IDE my attention was constantly
directed *away* from stuff I wasn't currently working on or
currently testing.
When you are coping with over 100,000 lines of code,
tools that help you *NOT* read are desperately valuable.
> And COBOL's DIVISIONs made sense when you could get color-coded
> pre-punched DIVISION cards in the keypunch rooms, to save time typing
> and to help you see, from the top of the deck, which division was
> which. Also good back when a COBOL compiler might have five-to-eight
> passes, on a machine with 4K instruction space: you could write a
> customer parser for each pass.
COBOL doesn't have _that_ many DIVISIONs.
IDENTIFICATION, ENVIRONMENT, DATA, and PROCEDURE,
in COBOL 85. In a program with a couple of hundred
lines, having those cards pre-punched saved practically
no time. Using the colour-coded stock to punch
semantically-named SECTIONs made a lot more sense.
Just in case that semantic categories means that functions that belong
together are placed together, I solve that kind of problem by having the
same prefix on functions that deal with the same thing.
On Wed, 2012-09-12 at 12:10 +0200, o...@cs.otago.ac.nz wrote:
> > I can understand that if you know what you're looking for (and just want
> > to check, say, function signature), then the alphabetic ordering may help.
> > However, if one wants to find out what is particular module
> > doing/responsible for, I would really like to learn how can alphabetic
> > ordering help.
> Just to make it clear, I was advocating that the list of
> function names in an -export directive should be sorted,
> while the function definitions should be grouped into
> semantic categories.
> Two historic comparisons:
> * the Burroughs Extended Algol compiler had a long list
> of forward procedure declarations near the front, each
> with an associated sequence number. Then the actual
> procedure definitions were grouped semantically. One
> typically kept a couple of punched cards stuck in the
> six-inch listing as bookmarks, one or more of them in
> the index. You could find your way around in this
> huge listing with astonishing ease.
> * the Smalltalk 5-pane browser (yes, I know I said 4-pane
> in a previous essage, but I'm typing with a laptop on
> my chest and am not catching all my typos).
> Top, left to right:
> class categories (think 'applications'), alphabetically
> classes within current category, alphabetically
> method categories within class (semantic sections), alphabetically
> methods within category, alphabetically
> Bottom:
> Edit window for class definition, class comment,
> or method definition.
> Add in the 'find definition' 'find callers' and other
> single keystroke operations, and you can really *fly*
> in that interface. Oh, guess what? No junk comments!
> If you want to find out what a module is doing or responsible
> for, you should be reading the module comment, not looking at
> the functions. And there should BE one that TELLS you.
> Note that if you have semantic -sections, then
> egrep '^-(module|section)' foobar.erl
> would tell you quite a bit about what the module is up to.
> When trying to "find out what is particular module doing/responsible
> for", on paper, it helps if you can find things. When reading on paper
> it is easier to find things when they are alphabetically ordered.
I suggest that a listing generator that appends a table of contents
mapping each function name to a page number is another way to do this.
I really don't care for any syntactic ordering principle.
For example, separating the exported functions from the private
ones is a bad idea, because I might want to conceal something
that used to be exported, or vice versa, and suddenly what *should*
be a one-line change is a big change.
With alphabetic ordering, again, what *should* be a small change
to the name of a function -- with corresponding changes to callers --
becomes a violent change of place.
I agree 100% that being able to find things alphabetically is
very useful. If it comes to that, being able to find functions
by who last edited them, or when they were last edited, or how
many bugs have been found in them, &c &c can be convenient.
That doesn't mean that any of these, or any other extrinsic
ordering, is a good way to organise a group of definitions
that need to be comprehended together.
Let's put it this way:
for things that do NOT have to be comprehended together,
alphabetic ordering is great;
for things that DO having to be comprehended together,
any extrinsic ordering is bad.
Let me give an example.
It's really simple one just to make a point.
-export([ ... sum/1 ...]).
sum(Xs) -> add_up(Xs, 0).
add_up([X|Xs], S) -> add_sup(Xs, S+X);
add_up([], S) -> S.
If the comment on sum/1 is not enough,
you have to read them *together*.
But if you separate exported functions from internal ones,
these two functions are on different pages.
If you order function definitions alphabetically,
these two functions are on different pages.
On 12 Sep 2012, at 12:27, o...@cs.otago.ac.nz wrote:
>> "Reading code on paper" has already been mentioned some times in this
>> thread.
>> But really people read code on paper, nowadays?
> Yes, me, lots.
The problem is often the same when reading code in a tty (which typically
defaults to 80x25). If I need to browse code from a command line, on a laptop with a 15" screen, I do tend to mutter a few curses in the direction
of programmers who seem to think that everyone is sitting in front of a lineup of >27" screens, just because they happen to. ;-)
This is hardly a new problem. In my first serious project, I recall an incident
where the coders of a UI had become too enamored with their new 17"
screens, and completely forgot that the most important users were using
Mac SE30s (with a 9" screen), for the simple reason that they had to jump out of airplanes with them.
A spicy brew of fighter-pilot language was hurled at the developers when
it was discovered that the new decision support system was unusable on
anything but the very latest, sexiest monitors that only the developers had.*
BR,
Ulf W
* As you can guess, this was in the 90s, when a 17" monitor was indeed sexy.
