Style

[Luke Gorrie]

"Martin J. Logan" <mlogan@REDACTED> writes:

> I the programming rules documentation on erlang.org it states
> 
> "Comments within Erlang code shall start with one percent character (%).
> If a line only contains a comment, it shall be indented as Erlang code.
> This kind of comment shall be placed above the statement it refers to.
> If the comment can be placed at the same line as the statement, this is
> preferred."
> 
> I use the erlang mode for emacs to edit my code and must wonder why it
> forces comments with a single percent sign to the far right of my
> screen. This is not consistent with the programming rules. Should this
> be changed?

The stated rules should be updated IMO. %% starts a whole-line
comment, and % starts an inline comment. As in:

  %% comment about the following function
  foo() ->
      %% comment about the following line
      stuff().            % inline comment about this line

That's how pretty much all the Erlang code in the world is written as
far as I can see. (Most importantly the Erlang/OTP code itself).

Note that the Emacs command M-; can be used to create aligned inline
comments. The variable `comment-column' says where to align them.

On the topic of programming style rules, there is an extremely good
tutorial for Common Lisp called the "Tutorial on Good Lisp Programming
Style" by Peter Norvig and Kent Pitman. Most of it applies equally to
Erlang. Maybe useful source material for people teaching Erlang
programming? URL is http://www.norvig.com/luv-slides.ps

I have one page from it pinned up next to my computer. It is a
reminder of commonly useful higher order functions, including the ones
that you don't use every day. It could be paraphrased for Erlang's
'lists' module thus:

  Control Abstraction:

  Most algorithms can be characterised as:

    * Searching: member/2, any/2, keysearch/3

    * Sorting:   sort/1, sort/2, keysort/2

    * Filtering: filter/2, dropwhile/2, takewhile/2, list comprehensions

    * Mapping:   map/2, mapfold[lr]/3

    * Combining: fold[lr]/3, flatmap/2, list comprehensions

  These higher-order functions abstract common control patterns. Code
  that uses them is:

    * Concise

    * Self-documenting

    * Easy to understand

    * Usually efficient

  Introducing your own higher-order functions is an important part of
  program design.

(Very Robert Virding :-))

Cheers,
Luke