[flashrom] Namespace prefix for libflashrom

[Stefan Tauner]

On Sat, 22 Apr 2017 11:16:18 -0700
David Hendricks <david.hendricks at 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.
libflashrom_ is probably too long but would at least transport the
meaning best in my opinion.

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.


Side note because I don't have the time yet to do proper reviews but I
have briefly looked at nico's libflashrom.h:

> struct flashprog;
> typedef struct flashprog fl_flashprog_t;
> struct flashctx;
> typedef struct flashctx fl_flashctx_t;

Please avoid type abstraction with no good reason (i.e. if there are
no alternative implementations that need to be abstracted). Also, please
avoid the _t suffix, which is reserved by POSIX (the broadness and
widespread infringement of this reservation are debatable but is nuked
anyway if there is not typedef to begin with ;).
There is nothing wrong with struct fl_programmer and struct fl_context
or struct fl_ctx... or whatever the prefix is. Actually, I deem the
former superior to "flashprog" which could mean a number of things e.g.
in
  int fl_flash_probe(fl_flashctx_t **, const fl_flashprog_t *, const char *chip_name); 
I can come up with at least these meanings: program, programmer, progress.

Another side note:

> Moving forward is currently more important than finding the perfect name.

With that attitude you (plural) are destined to create just another
fork(-ish branch). From what I gathered up so far from the gerrit
activity this is possible happening already anyway and it might
actually be successful (although unintended nand/nor ill-intended and I
don't blame you). I will try to give some more feedback soon.
-- 
Kind regards/Mit freundlichen Grüßen, Stefan Tauner