[erlang-questions] Which choice is better? Function or Case

[Joe Armstrong]

On Sat, Mar 9, 2013 at 3:13 PM, Henning Diedrich <hd2010@REDACTED>wrote:

> Hi list,
>
> I realize I keep coming back to the question, even on Saturdays, did
> Gianfranco mean more comments, or less.
>
> On Mar 8, 2013, at 1:54 PM, Gianfranco Alongi <gianfranco.alongi@REDACTED>
> wrote:
>
> > Therefore, minimize the time needed to read your code, making it cheaper.
> >
>
>
> In likeliness, I fancy, you meant neither and the balance between
> cluttering the source into unreadability or under commenting is as delicate
> as the coding itself.
>
> While the language already offers different ways to achieve the same
> thing, how much more liberty is there in commenting.
>
> Robert one time suggested the Church of Short Variable Names to me as a
> way to reduce Erlang's occasional verbosity.
>
> Once you dare writing one-letter variables, it makes a difference like
> night and day. It is, on the face of it, so much easier to read.
>
> But using single letter variables all but makes comments part of the code.
> One may claim the code to be close to useless without the comments.
>

I try to use very short variable names. In my mind variable names carry to
meaning. I'm very very fussy about extremely accurate function names. If a
function says do_this_and_that it should do exactly this_and_that and not
something else.

Also comments should be extremely accurate . Non-obvious tricks should be
explained in detail. Obvious things should not be commented.

Comments should be repaired with the same lova and care as code. Without
spelling and punctuation errors. If I see a typo in a comment my brain says
"this program is not yet ready for publication" - practising the art needs
fine
attention to detail.

I actually think one should publish (for each module)

    - a .hrl file for each module with comments and function specs and types
    - documentation for the module
    - a .beam file

    and NO .erl file (should be available on demand)

    Doing this would really test if you code is sufficiently well described
for
somebody else to actually use.

   If somebody has to read your code to figure out what it does you have
failed.

   (This is yet another reason why programming is difficult and takes time)

Cheers

/Joe






>
> Since we just saw specs evolving from comment annotations to language
> part, I wonder if that is a pointer:
>
> what part of the comments are to be considered mandatory part of the code,
> beyond specs, which latter had type verification as focus.
>
> What other commenting part that has semantics as focus would emerge, not
> to create new restrictions but as a guide line to support one's future
> self, or whoever inherited your code?
>
> This, in part, goes back to Joe's proposal to annotate the Internet. While
> that was not about form but more of a technical discussion, the inspiration
> is similar.
>
> Henning
>
>
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://erlang.org/pipermail/erlang-questions/attachments/20130309/99ed53e5/attachment.htm>