Re: [Qemu-devel] [PATCH] CODING_STYLE: Define how to handle acronyms in CamelCase

[Blue Swirl]

On Wed, Sep 26, 2012 at 9:59 PM, Anthony Liguori <address@hidden> wrote:
> Alex Williamson <address@hidden> writes:
>
>> When creating structure names in CamelCase, it's easy to have
>> back-to-back capitals when using acronyms (ex. PCIINTxRoutingNotifier,
>> QEMUSGList, VFIOINTx).  In the worst case these can look like macros,
>> but even adjoining a single, all-caps acronym makes it more difficult
>> to interpret.  For example, is PCIIntxRoutingNotifier sufficiently
>> more clear?  Mixing case, such as VFIOintx isn't truly CamelCase.
>> Therefore let's abandon all-caps acronyms in CamelCase, resulting in
>> PciIntxRoutingNotifier, QemuSgList, VfioIntx.
>>
>> Cc: Michael Tsirkin <address@hidden>
>> Signed-off-by: Alex Williamson <address@hidden>
>> ---
>>
>> This is an attempt to formalize and get agreement on name changes
>> suggested for the vfio-pci driver.  VFIO is very prone to these naming
>> problems.  I don't expect to do any massive code churn to correct
>> these, but I will update vfio-pci to whatever outcome we decide and at
>> least we'll have a reference rather than per maintainer policy.
>> Thanks,
>>
>> Alex
>>
>>  CODING_STYLE |    5 +++++
>>  1 file changed, 5 insertions(+)
>>
>> diff --git a/CODING_STYLE b/CODING_STYLE
>> index dcbce28..e45ed1a 100644
>> --- a/CODING_STYLE
>> +++ b/CODING_STYLE
>> @@ -53,6 +53,11 @@ and is therefore likely to be changed.
>>  When wrapping standard library functions, use the prefix qemu_ to alert
>>  readers that they are seeing a wrapped version; otherwise avoid this prefix.
>>
>> +When making use of acronyms in CamelCase only capitalize the first character
>> +of the acronym.  This promotes readability and clearly defines the start of
>> +each word or acronym.  For example, instead of PCIBAR, use PciBar.  In place
>> +of QEMUDMAList, use QemuDmaList.
>> +
>
> I'd prefer not to do this.
>
> We do both within QEMU and I think that's fine.  By choosing one vs. the
> other we just create a lot of friction because now people have to
> introduce structures that aren't consistent with the rest of the file.

I think PCIBAR and PciBar look equally ugly, so I'd agree.

>
> Either is fine IMHO.
>
> Regards,
>
> Anthony Liguori
>
>>  4. Block structure
>>
>>  Every indented statement is braced; even if the block contains just one
>