[libvirt] [PATCH v2] Document preferred naming conventions

[Jiri Denemark]

On Fri, Mar 03, 2017 at 19:16:58 +0000, Daniel P. Berrange wrote:
> On Fri, Mar 03, 2017 at 07:57:24PM +0100, Jiri Denemark wrote:
> > On Fri, Mar 03, 2017 at 17:47:23 +0000, Daniel P. Berrange wrote:
> > > This documents the preferred conventions for naming files,
> > > structs, enums, typedefs and functions.
> > > 
> > > Signed-off-by: Daniel P. Berrange <berrange at redhat.com>
> > > ---
> > > 
> > > Changed in v2:
> > > 
> > >  - Fix typo
> > >  - Add macro docs
> > >  - Clarify that $VERB is always last in function/macro names
> > 
> > Hmm, so what do we do if there is an object, an action, and a subject?
> 
> Good question :-)
> 
> > Typically accessors which are designed to return some specific part of
> > the object. For example,
> > 
> >     virQEMUCapsGetDefaultMachine
> >     \         / | \            /
> >        object   |    subject
> >                 |
> >                 `- action (verb)
> > 
> > Are we supposed to name such function as virQEMUCapsDefaultMachineGet?
> > While it is certainly possible, it just doesn't read well.
> 
> Yeah that's craziness in that example at least. Do you recall any examples
> where we have object,subject,action, or are we always doing
> object,action,subject ?

I went through qemu_capabilities.c and found a few examples which do not
follow object,action,subject:

virQEMUCapsCPUFilterFeatures
- this is strange and should be changed

virQEMUCapsQMPSchemaObjectGetType
virQEMUCapsQMPSchemaTraverse
virQEMUCapsQMPSchemaGetByPath
- these are quite innovative, they look as if
  virQEMUCapsQMPSchema{,Object} were objects on which the functions
  operate, but there are no objects with such names defined; still I
  think the names don't need to be changed

> We could specify object,action,subject, or we could just say either
> ordering of action & subject is valid.

Maybe we could specify object,action,subject, while still allowing other
variants if they read better (although I can't think of any example).

Jirka