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