Re: [libvirt] [PATCH v2] Document preferred naming conventions
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(a)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