[erlang-questions] Request feedback on example project

[zxq9]

On 2016年2月4日 木曜日 07:29:06 Nathaniel Waisbrot wrote:
> >
> > I don't even like the idea of using maps for this, but the "old
> > fashioned" tuple type seems to be discouraged in the R18 docs. Meh.
> >
> > So much for trying to be hip to the new thing. I like my old tuples.
> > I don't think there is anything in here that doesn't work even with
> > rather old ERTS releases, so I'm switching this (back) to tuples.
> > With regard to tuples VS maps for trivial things like this... I almost
> > feel like its a case of getting a newfangled toy and simply feeling
> > compelled to use it everywhere.
> 
> As someone with less than 10,000 hours of OTP code under my belt, I found
> this change (tuples to maps) to be so useful that I immediately upgraded
> all my code to require version 18.
> With the tuples, I had to check the documentation every single time I made
> a supervisor to confirm whether it was `intensity` or `period` first. I
> also would get copy/paste errors because I'd copy the child spec for a
> worker that was set to `brutal_kill` and use that as template for a
> supervisor without changing it to `infinity`.
> The new maps are self-documenting and they provide sane defaults so that if
> I want a vanilla supervisor I can just say `#{id => cool_super, start =>
> {M, F, A}, type => supervisor}`.  Not only do I avoid dumb bugs, but it's
> also clear that this is a vanilla supervisor and not something more
> interesting.
> 
> It seems like a small change, but I thought the old tuples were _awful_ and
> I was very happy to see them marked as deprecated.

Having a method for defaulting to sane values (using maps for convenience)
makes perfect sense. But *deprecating* tuples bothers me -- it means that
eventually every piece of OTP code is going to break or have to be
(arbitrarily) moved forward to maps for no gain.

Ideally, if I could have my way... and actually I can, so I'm going to add
something like this to my own templating tool...

  vanilla_worker(Name) ->
      vanilla_worker(Name, []).

  vanilla_worker(Name, Args) ->
      {Name,
       {Name, start_link, Args},
       permanent,
       brutal_kill,
       worker,
       [Name]}.

...And maybe one or two more really common ones.

I find it every bit as annoying to define a bunch of nearly identical
maps as a bunch of nearly identical tuples. I generally only have to do
this from scratch *once* per project, which is really not a big deal.
Its annoying either way, but its typically a one-off annoyance.

(Until now I've just had a template I have a script pull over and start
from there, so I sort of forgot that this could be annoying.)

> > Oh, a layout issue.  I don't like big black blobs (except when I
> > > write them).  So
> > > %% wdrwertwertwert
> > > %% wertwertwertwrt
> > > %% wretertwertwertew
> > > -spec frgsdfgdfghsdfg
> > > asdfasdf(sdfgsdfg) ->
> > >     ....
> > >
> > > is just a bit too much for me to be comfortable with.  I'd find
> > > it easier to read with blank line after the %% comment block
> > > and a blank line after the -spec.
> > >
> > > I find that with my OWN code it's so obvious that packing it
> > > tightly doesn't impair readability, but with someone else's
> > > code well-placed blank lines never go amiss.  I can only suppose
> > > that I'm in error about my own code and that it too could do with
> > > more blank lines.
> >
> > *MY* code is always perfectly readable as big, immaculate, unbroken
> > blocks. Until a few months later. Ugh.
> >
> > I'm not sure where I stand on the line break issue, really, but since
> > you mentioned it I'm trying out a line between doc and spec, a line
> > between spec and definition, and two lines between functions (but no
> > lines between function clauses -- I already know that confuses me,
> > especially with un-specced/un-docced functions).
> >
> 
> 
> I don't feel very strongly on this one (I do about the supervisor spec),
> but I find the tight-packed blocks _more_ readable in other people's code.
> I run my eyes down the left-hand side and see
> 
> %
> -
> a
> 
> And that's pretty clearly (1) some comments, (2) a compiler directive, (3)
> a function. They all go together: I expect the comment to be function
> documentation and the dash to be a function spec.
> 
> If I see
> 
> %
> 
> -
> 
> a
> 
> Then the comments might be module-level comments and the directive might be
> an export or an if or a define or a type declaration and I have to read
> more characters to figure out if those three lines are related.

I sometimes think so myself. In this case, though, where every function has
an explicit `%% @doc` at the head of the function docs and everything else
follows a pretty obvious pattern, I do indeed find it easier with the extra
lines. With a mishmash of styles in a single source file, though... ugh. I
think it would get really annoying. Tomorrow I'll check again and see which
I like. Part of my goal here is to get some feedback before I start doing
more open-source stuff... the place I've been coding the last year has been
rather niche and impossible to make generally applicable someplace like
github.

On second thought, I think the extra newlines actually improve *reading*
but may somewhat impare *scanning*.

Consider:
https://github.com/zxq9/zuuid/blob/master/src/zuuid.erl

One clear advantage is that my super-lazy-man's navigation in vi is far
more precise now, as each function and spec had is the start of what the
editor sees as its own block. Not a big deal (I usually jump directly to
wherever I want to go), but it is sort of nice.

-Craig