[flashrom] Namespace prefix for libflashrom

[David Hendricks]

On Sun, Apr 23, 2017 at 7:07 AM, Stefan Tauner <stefan.tauner at gmx.at> wrote:

> 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.
>

Agreed.


> 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.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.coreboot.org/pipermail/flashrom/attachments/20170423/4bd9b21f/attachment-0001.html>