On Sun, Apr 23, 2017 at 7:07 AM, Stefan Tauner <stefan.tauner@gmx.at> wrote:
On Sat, 22 Apr 2017 11:16:18 -0700
David Hendricks <david.hendricks@gmail.com> wrote:

> Thanks for getting this discussion going on the list, Nico.
> For reference, folks can view the proposed libflashrom.h at
> https://review.coreboot.org/#/c/17946 to get a better idea for how these
> prefixes will look in libflashrom functions and data structures.
> Also, let's add "fi_" for flashrom interface to the list of proposed
> prefixes.
> My preferences (in order):
> 1. lf_
> 2. flashrom_
> 3. fi_
> 4. fl_
> 5. flash_
> 6. fr_
> IMO not only is "lf_" most intuitive, but the way the keys are spaced apart
> comfortably on qwerty, dvorak, and colemak layouts and each character
> (including the underscore) use a different hand to type. Same could be said
> about fl_ with regards to keyboard layout. fr_ is awkward (keys vertically
> adjacent) on qwerty and colemak, and fi_ is vertically adjacent on dvorak.
> flash_ and flashrom_ are not bad but are obviously many more keystrokes.

I value giving thoughts to details, but in this case I reside more with
torvalds: "if your typing speed is the main issue when you're coding,
you're doing something seriously wrong."

In my opinion the prefix has to satisfy a number of requirements:

 - no ISO C(99/11) or POSIX violations
 - no easy collisions with other libraries or user functions
 - easily recognizable prefix for humans associated with the concept of
   libflashrom (i.e. some kind of abstraction to interact with NOR
   flash chips via different programmers)
 - reasonable short length to avoid overly long function names etc.
   based on the prefix

> flash_ is pretty good - For the most part it flows well with functions such
> as flash_image_read() and flash_image_write(), but is awkward with some
> other stuff like "flash_set_log_callback()". If we're already typing >2
> letters I think we ought to just use flashrom_ as the prefix to be
> complete, avoid awkward contexts, and avoid namespace conflicts (users
> might want to use flash_ in their code).

flash_ seems to me a bit too concrete... it gets (too) easily associated
with the actual memory device and not so much to libflashrom IMHO.

flashrom_ is quite long and would be associated with flashrom (the
utility) and would make it harder to distinguishing the library from
the program.

I don't see why that distinction is important.

libflashrom_ is probably too long but would at least transport the
meaning best in my opinion.

Agreed. And if a user of the library really hates typing that many letters then they can create trivial wrappers.

So... shorter but conveying the same meaning:

 - lflashrom, lfrom: meh
 - lflashr: would require a new awful website with flash chips dancing
   for no good reason ;)
 - lf: was already mentioned, I deem it a bit too short and ambiguous
 - fl: too easily misinterpreted as a flashrom function prefix IMHO -
   the aspect of being a library is important to me.
 - libf: would be in the tradition of short-named unix libraries (and
   seems to be unused actually as a library name), but does not really
   improve on lf and would make it look way too important than it is :)
 - lfr: was proposed in the wiki, possibly by myself - can't remember.
   This might be the optimal compromise: intuitive if you heard it
   once, probably quite unique and very short.
 - lfl: might also work if neither lfr nor lf are acceptable (but why
   would lfl then be :)

Thus my favorites are basically
 - lfr_
 - libflashrom_
 - lf_

I'd love to hear some arguments about your preferences.

I'd be fine with libflashrom_. Since it seems there is no definitive favorite short prefix I think we should just forget about those and use a longer one. And in the grand scheme of things neither libflashrom_ nor flashrom_ are very long.

For the public API we just need to pick something that's intuitive and unlikely to collide. The user can always write shorthand wrappers that fit into their program's namespace if they call the library functions often enough to make the extra characters feel burdensome.