[erlang-questions] Style wars: junk comments

[Ivan Uemlianin]

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.



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)
============================================================