[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

[Peter Stuge]

Paul Menzel wrote:
> 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.

NAK..
> coreboot should be attractive to hobby hackers too

I'm afraid that's just wishful thinking. Please look at the reality
of modern platform development. Hobby hackers can't contribute there.
> 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.

Let's optimize for the common case.. Every hobby hacker needs to
look up each acronym only once, and the cost of that lookup is small
in terms of commited lines of code. Typing out acronyms in each
commit message, no matter how fast one types, will always have higher
cost in terms of committed lines of code.

That said, I completely agree that commit messages are an important
way to transfer knowledge and that they should always be thoughtfully
written, but in reality not everyone will do that.

//Peter

[David Hendricks]

On Tue, Mar 19, 2013 at 3:41 PM, Paul Menzel <
[e-mail]> wrote:
> 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.

Programming at the low-level in firmware and drivers often means turning
datasheets into functional code, so it is important to use acronyms,
mnemonics, and other terminology consistent with vendor-provided
documentation. Otherwise searching for a particular value, register name,
etc. can be very frustrating.

PDF readers are a few years behind Google in terms of contextual search ;-)

[ron minnich]

I agree with others that this is a Bad Idea Always (BIA).

ron