[erlang-questions] Style wars: junk comments
Wed Sep 12 14:05:15 CEST 2012
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.
> 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:
>>> 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
>>> 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 mailing list
> erlang-questions mailing list
More information about the erlang-questions