[erlang-questions] Style wars: junk comments

[Steve Davis]

Yes, to me that stuff seems to be obvious and distracting BS. 

e.g. anything "internal" isn't exported by definition, right?

There *is* an issue between making a distinction between -export for API 
use and -export needed for use only within the app or library.

Anything else is not a weakness of erlang syntax IMHO. 

/s

On Wednesday, September 12, 2012 2:56:31 AM UTC-5, Richard O'Keefe 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-q...@REDACTED <javascript:> 
> http://erlang.org/mailman/listinfo/erlang-questions 
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://erlang.org/pipermail/erlang-questions/attachments/20120913/9fdfc242/attachment.htm>