| Message ID | 20120924175746.15361.32976.stgit@bling.home |
|---|---|
| State | New |
| Headers | show |
On Mon, Sep 24, 2012 at 12:08:16PM -0600, Alex Williamson wrote: > 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 <mst@redhat.com> > Signed-off-by: Alex Williamson <alex.williamson@redhat.com> I'm fine with these, but you should ask people like Blue Swirl who really care about coding style rules. > --- > > 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. > + > 4. Block structure > > Every indented statement is braced; even if the block contains just one
On Mon, 2012-09-24 at 22:01 +0200, Michael S. Tsirkin wrote: > On Mon, Sep 24, 2012 at 12:08:16PM -0600, Alex Williamson wrote: > > 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 <mst@redhat.com> > > Signed-off-by: Alex Williamson <alex.williamson@redhat.com> > > I'm fine with these, but you should ask people like Blue Swirl > who really care about coding style rules. Blue, any preference? Is this needed? Thanks, Alex > > --- > > > > 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. > > + > > 4. Block structure > > > > Every indented statement is braced; even if the block contains just one
Alex Williamson <alex.williamson@redhat.com> 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 <mst@redhat.com> > Signed-off-by: Alex Williamson <alex.williamson@redhat.com> > --- > > 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. Either is fine IMHO. Regards, Anthony Liguori > 4. Block structure > > Every indented statement is braced; even if the block contains just one
On Wed, 2012-09-26 at 16:59 -0500, Anthony Liguori wrote: > Alex Williamson <alex.williamson@redhat.com> 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 <mst@redhat.com> > > Signed-off-by: Alex Williamson <alex.williamson@redhat.com> > > --- > > > > 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. > > Either is fine IMHO. Fair enough, thanks, Alex
On Wed, Sep 26, 2012 at 9:59 PM, Anthony Liguori <anthony@codemonkey.ws> wrote: > Alex Williamson <alex.williamson@redhat.com> 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 <mst@redhat.com> >> Signed-off-by: Alex Williamson <alex.williamson@redhat.com> >> --- >> >> 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 >
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. + 4. Block structure Every indented statement is braced; even if the block contains just one
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 <mst@redhat.com> Signed-off-by: Alex Williamson <alex.williamson@redhat.com> --- 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(+)