[erlang-questions] Style wars: junk comments

[Vlad Dumitrescu]

This is slightly the wrong crowd to mention erlide to :-) but it can
also navigate to the definition of things. This discussion also
prompted me to create a ticket for an feature where the related
functions can be shown together in the editor, regardless of where
they are located in the file. Also we could group and arrange the
source code too, using topological sort based on the dependencies.

regards,
vlad

On Wed, Sep 12, 2012 at 2:05 PM, Anton Lebedevich <mabrek@REDACTED> wrote:
> 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
>
> _______________________________________________
> erlang-questions mailing list
> erlang-questions@REDACTED
> http://erlang.org/mailman/listinfo/erlang-questions