[coreboot] [RFC] Abbreviations in commit messages and code

[Paul Menzel]

Dear coreboot folks,


following up on Ron’s comment to Gerrit item(?) 2695 [1]

        We can't break out each and every vendor TLA (Three Letter
        Acronym) or we'll be here for years. I understand the possible
        confusion, but at the same time, there are terms of the art that
        we just use, ULT, PCI, DMA, HT, PNP, I2C, being some of them.
        It's a dreadful learning curve, but we all get to climb it :-)

I propose the following rule (suggestion, guideline) for usage of
abbreviations in commit messages and code.

        Abbreviations – mostly three letter acronyms (TLA) – should be
        written out in full additionally once when used the first time
        in a file or commit message, when no Wikipedia article exists
        for that abbreviation or pops up when searching for that
        abbreviation.

Following that rule, PCI, USB or GPIO would not have to be written out
fully, but CRB (Customer Reference Board) or ULT (low power Haswell
variant) would be needed to be written out or explained once.

The reasoning is that coreboot should be attractive to hobby hackers too
and not having to look up these terms saves them some time and eases the
“dreadful learning curve” in my opinion. Especially writing them out
takes programmers less than five seconds as they can type really fast.

Following this rule would make it easier for outsiders to dive into
coreboot.

What do you think? If you agree, I’ll put it to the development
guidelines or Git section of the coreboot Wiki.


Thanks,

Paul


[1] http://review.coreboot.org/#/c/2695/3//COMMIT_MSG
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 198 bytes
Desc: This is a digitally signed message part
URL: <http://www.coreboot.org/pipermail/coreboot/attachments/20130319/b8f4d7b9/attachment.sig>