[erlang-questions] Request feedback on example project

[zxq9]

On 2016年2月6日 土曜日 09:28:40 you wrote:
> On Wed, Feb 3, 2016 at 7:00 AM, zxq9 <zxq9@REDACTED> wrote:
> > Two days ago I wrote a simple UUID utility as an example of bit syntax.
> > Yesterday I decided I wanted it to be an example of documentation and
> > readability as well.
> 
> I took a quick look and liked what I saw.
> 
> In my opinion one should publish documentation and compiled code.
> If the user needs to see the source then the documentation is inadequate
> source should be available if requested and for the purpose of modification
> but not because the documentation is inadequate.
> 
> You documentation is excellent.
> 
> One tiny point in
> 
> http://erlang.org/pipermail/erlang-questions/2015-March/083879.html
> 
> I argued that interfaces should be *minimal* - you export uuid:string
> and uuid:binary
> 
> I'm beginning to dislike code where I can call functions with polymorphic
> arguments, filenames that can be strings, atoms, I/O lists whatever.
> 
> I feel like shouting - "make you mind up". Do you want me to call your
> library through the string or binary interface?
> 
> I would reason like this. "Should a user see the printed representation of
> UUIDs or should they be hidden from sight?" I think UUID's should not
> be seen by humans only by programs - therefore only the binary interface
> should be available which will encourage this usage. So remove the
> uuid:string functions.

I agree wholeheartedly.

In this case uuid() [1] is its own internal type. This is the only type
accepted by zuuid:string/2 [2] and zuuid:binary/2 [3]. The string and
binary functions are output-only, to convert the internal uuid() type to
serialized representations required by various databases and frameworks
(its not compliant with RFC 4122 if it can't at *least* output a canonical
string representation of a UUID). Without those output options this
application would not be very useful.

You can't pass an arbitrary representation to string/2 or binary/2, but
you must be able to pass an arbitrary representation (especially any
form corresponding to the canonical string representation in RFC 4122)
to the external-to-internal function, read_uuid/1. Without this it would
be impossible to interoperate with pretty much any other UUID tools.
Postgres returns the equivalent of zuuid:binary(UUID, brackets), for
example -- so at a minimum that must be readable.

I'm not disputing your points -- the API reflects my approach to dealing
with them. If there is a better way I am all ears.

If the API is *confusing* or there is an obviously better way to provide
this functionality, though, I would really like to know. (I already
deprecated string/1 and binary/1 because they really were half-baked.)

-Craig

[1. http://zxq9.com/projects/zuuid/docs/zuuid.html#type-uuid]
[2. http://zxq9.com/projects/zuuid/docs/zuuid.html#string-2]
[3. http://zxq9.com/projects/zuuid/docs/zuuid.html#binary-2]