[erlang-questions] Style wars: junk comments

[Anton Lebedevich]

Distel helps a lot for reviewing code on screen. It has function
erl-find-source-under-point, which is bound to M-. This function allows
to jump to the source code that defines the function being called at
point. erl-find-source-unwind bound to M-, allows to return back after
reading the function.

On 09/12/2012 12:42 PM, 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