[erlang-questions] Style wars: junk comments

[Bengt Kleberg]

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
>