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