[erlang-questions] Style wars: junk comments
Michael Turner
michael.eugene.turner@REDACTED
Wed Sep 12 11:20:24 CEST 2012
On Wed, Sep 12, 2012 at 6:12 PM, Ivan Uemlianin <ivan@REDACTED> 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.
Just saying.
^_~
-michael turner
> On 12/09/2012 10:00, 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
>>
>
>
> --
> ============================================================
> Ivan A. Uemlianin PhD
> Llaisdy
> Speech Technology Research and Development
>
> ivan@REDACTED
> www.llaisdy.com
> llaisdy.wordpress.com
> github.com/llaisdy
> www.linkedin.com/in/ivanuemlianin
>
> "hilaritas excessum habere nequit"
> (Spinoza, Ethica, IV, XLII)
> ============================================================
> _______________________________________________
> erlang-questions mailing list
> erlang-questions@REDACTED
> 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
turner@REDACTED
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
More information about the erlang-questions
mailing list