[erlang-questions] Style wars: junk comments

[ok@REDACTED]

> 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.

I suggest that a listing generator that appends a table of contents
mapping each function name to a page number is another way to do this.
I really don't care for any syntactic ordering principle.

For example, separating the exported functions from the private
ones is a bad idea, because I might want to conceal something
that used to be exported, or vice versa, and suddenly what *should*
be a one-line change is a big change.

With alphabetic ordering, again, what *should* be a small change
to the name of a function -- with corresponding changes to callers --
becomes a violent change of place.

I agree 100% that being able to find things alphabetically is
very useful.  If it comes to that, being able to find functions
by who last edited them, or when they were last edited, or how
many bugs have been found in them, &c &c can be convenient.
That doesn't mean that any of these, or any other extrinsic
ordering, is a good way to organise a group of definitions
that need to be comprehended together.

Let's put it this way:
  for things that do NOT have to be comprehended together,
  alphabetic ordering is great;
  for things that DO having to be comprehended together,
  any extrinsic ordering is bad.

Let me give an example.
It's really simple one just to make a point.

    -export([ ... sum/1 ...]).

    sum(Xs) -> add_up(Xs, 0).

    add_up([X|Xs], S) -> add_sup(Xs, S+X);
    add_up([],     S) -> S.

If the comment on sum/1 is not enough,
you have to read them *together*.
But if you separate exported functions from internal ones,
these two functions are on different pages.
If you order function definitions alphabetically,
these two functions are on different pages.