Re: [flashrom] Namespace prefix for libflashrom

[Stefan Tauner]

On Sat, 22 Apr 2017 11:16:18 -0700
David Hendricks  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):
> lf_
> flashrom_
> fi_
> fl_
> flash_
> 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.

Namespace prefix for libflashrom

[Nico Huber]

On 23.04.2017 16:07, Stefan Tauner wrote:
> On Sat, 22 Apr 2017 11:16:18 -0700
> David Hendricks  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):
> > lf_
> > flashrom_
> > fi_
> > fl_
> > flash_
> > 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."

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

If we really want some sort of collision avoidance we should drop the
acronyms. They are just too short, IMO.
> 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.

Well, the program is the library plus the cli. So with the same argument
we would have to rename flashrom.c. Also who would have to distinguish?
Developers that use libflashrom would know that they use libflashrom
and not the program. And for flashrom developers, it wouldn't be to hard
either, since we don't use the `flashrom_` prefix anywhere (ok, beside
`flashrom_version`).
> 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_

With lfr_ and lf_ being very short, that would leave libflashrom_.
I'd still prefer flashrom_ over it. It's shorter and should be clear
enough to a developer.
> 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

Good reason: The implementation of the struct is completely hidden from
the library user anyway. AFAIR, I didn't use something like a `typedef
void *`, to keep the header compatible with the internal code.

But I have to admit, reading this over four years later, I also stumbled
a little. I'm not a fan of typedefs either.
> 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 ;).

Didn't know that.
> 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

It feels wrong to let the libflashrom user write `struct ...` if it's
not a struct to him.
> former superior to "flashprog" which could mean a number of things e.g.

Agreed. The name is just a placeholder. Now that it's there, I think
that we should back it up by a struct soon (flashctx would point to it)
and move some (if not all) of the flags I added to flashctx there. In
the long run, it should replace all the current global state ofc.
> 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.

That's why the interface is documented.
> 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.

I believe the past four years have shown that with your attitude
flashrom doesn't evolve anywhere on such matters. Also, the prefix can
be easily changed later. Nobody said the interface is frozen with the
first commit.

Regarding the branch, I was aware (that you might call it a fork).
Albeit, as far as I remember them, you'd have to adapt the develop-
ment guidelines to give it reason.

Nico

Namespace prefix for libflashrom

[David Hendricks]

On Sun, Apr 23, 2017 at 7:07 AM, Stefan Tauner  wrote:
> On Sat, 22 Apr 2017 11:16:18 -0700
> David Hendricks  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):
> > lf_
> > flashrom_
> > fi_
> > fl_
> > flash_
> > 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.