[erlang-questions] Style wars: junk comments

Robert Virding robert.virding@REDACTED
Wed Sep 12 13:11:21 CEST 2012 

No!

I find it much easier to understand what is going on if I group the main function together with its "helper" functions. They are working together as one unit and often the helper functions only have meaning within the context of the main function. It also makes it easier to comment the whole unit and have local comments where necessary. The comment to the main functions describes what this functions does and how it does it, while comments for the helper functions just describe features of that function. In many cases this is the erlang alternative to having local functions. The only problem is when helper functions are shared between main functions in which case I usually put them together with the first function.

I never order my API functions alphabetically but prefer to group them according to what they do. For example if there is a server I will have the start/start_link/stop functions together as they managed the server as a whole. I will group API functions after what they do, so I will put functions that access one property together.

I will also group my export declarations in a similar way, sometimes commented, just to make it easier to see which exported functions belong together.

Robert

----- Original Message -----
> From: "Bengt Kleberg" <bengt.kleberg@REDACTED>
> Cc: "Erlang-Questions Questions" <erlang-questions@REDACTED>
> Sent: Wednesday, 12 September, 2012 11:14:05 AM
> Subject: Re: [erlang-questions] Style wars: junk comments
> 
> 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
> > 
> 
> _______________________________________________
> erlang-questions mailing list
> erlang-questions@REDACTED
> http://erlang.org/mailman/listinfo/erlang-questions
>

More information about the erlang-questions mailing list