[erlang-questions] Request feedback on example project
Richard A. O'Keefe
Thu Feb 4 22:06:29 CET 2016
I've now written an AWK script to insert the extra blank lines
I wanted, and I found it helped me a *lot*.
On 5/02/16 1:52 am, zxq9 wrote:
> On second thought, I think the extra newlines actually improve *reading*
> but may somewhat impare *scanning*.
Fair comment. Thing is, I was trying to *read* the code.
For scanning the code, a scheme that begins every blob with
&c is unhelpful, because all I ever see as I skip forward is those
uninformative lines. When my eye (or the text editor's cursor)
comes to rest, I want it to be resting on the function name.
This means that to skip through the code in vi I need to do
Let's take a look at the first thing in zuuid.erl.
%% Starts the zuuid application, spawning a supervisor and a worker to
%% state generation details for version 1 and 2 UUIDs and ensure duplicates
%% will not occur even at high call frequencies (as suggested in
%% <a href="http://tools.ietf.org/html/rfc4122#section-4.2.1">RFC 4122,
WHAT starts the application?
The problem here is that I'm not so much reading internal documentation
as I am some sort of assembly code for internal documentation. The
information I *need* before I read these words, the information that *will*
be displayed in formatted documentation before these words, is in *this*
representation of the documentation many lines later.
Since the -spec line has the function name and may well list the
argument names and give a helpful name for the result (hint: Result is
not a particularly helpful name), I personally would find it more
readable if the order were
-spec <name>(<arguments>) -> <result>
name(...) -> ...
because in this order I would at least know what the @doc was *about*.
In this order it might make sense *not* to have a blank
line between the -spec and @doc because the @doc would
be a grammatical continuation of the -spec.
Maybe everybody else just runs files through edoc and puts
that in one window while they edit code in another.
More information about the erlang-questions