[erlang-questions] Style wars: junk comments

[Valentin Micic]

Hmmm…. maybe it's about time to go green? (Just kidding, of course… or am I?).

V/ 
On 12 Sep 2012, at 11:14 AM, Bengt Kleberg wrote:

> 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 <ok@REDACTED> wrote:
>>>>> 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
>>>>> 
>>>>> _______________________________________________
>>>>> erlang-questions mailing list
>>>>> erlang-questions@REDACTED
>>>>> http://erlang.org/mailman/listinfo/erlang-questions
>>>> _______________________________________________
>>>> erlang-questions mailing list
>>>> erlang-questions@REDACTED
>>>> http://erlang.org/mailman/listinfo/erlang-questions
>>> 
>>> _______________________________________________
>>> erlang-questions mailing list
>>> erlang-questions@REDACTED
>>> http://erlang.org/mailman/listinfo/erlang-questions
>> 
> 
> _______________________________________________
> erlang-questions mailing list
> erlang-questions@REDACTED
> http://erlang.org/mailman/listinfo/erlang-questions