[erlang-questions] Request feedback on example project

[zxq9]

On 2016年2月5日 金曜日 10:06:29 Richard A. O'Keefe wrote:
> On 5/02/16 1:52 am, zxq9 wrote:
> > but may somewhat impare *scanning*.
> s/impare/impair/

(O.o) I actually typed that. (>o<)

> Fair comment.  Thing is, I was trying to *read* the code.
> 
> For scanning the code, a scheme that begins every blob with
> %%@doc
> or
> %%@private
> &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
> /^[a-z']/ .
> 
> Let's take a look at the first thing in zuuid.erl.
> 
> %% @doc
> %% Starts the zuuid application, spawning a supervisor and a worker to 
> manage
> %% 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, 
> 4.2.1</a>).
> %%
> 
> 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>
>   ...
> %%@doc
> ....
> %%
> 
> 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.

This is a really good point, especially with functions that have lengthy
doc comments above them. Looking at some other code for context, my eye
(and editor) really does pick up about the first line or two of the doc
comment, then jump to the spec or function head, then jump back up to
continue reading the doc. I've never considered how silly this procedure
actually is.

I've switched them around now and the effect (especially now that I'm
expecting it) is magical.
https://github.com/zxq9/zuuid/blob/master/src/zuuid.erl

Much easier to visually navigate. It is actually very readable even in
plain, unhighlighted text now -- this is sort of the gold standard for
readability in my mind.

Thanks, again!

-Craig