Re: [libvirt] [PATCH v2] Document preferred naming conventions
On 03/03/2017 02:16 PM, Daniel P. Berrange wrote:
On Fri, Mar 03, 2017 at 07:57:24PM +0100, Jiri Denemark wrote:
>
> 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 ?
Just to throw more wrenches in the works: There are a *lot* of
auto-generated function names like virEnumNameTypeFromString() and
virEnumNameTypeToString(). If we ever decided we wanted full consistency
(as if that is even *possible* :-P), would we make those
virEnumNameGetString() and virStringGetEnumName() ? (but of course then
some pedant would expect virStringGetEnumName() to be in virstring.[ch] :-P)
This discussion is apropos for me, as I just made a new function that
turns an SRIOV PFnetdevname + VF# into a VFnetdevname. I had just
mindlessly called it virNetDevGetVFFromPF() (existing functions spell
out PhysicalFunction and VirtualFunction but I think that's too long
even when only one is involved), but after reading through this and
actually *thinking* about it, I renamed it to virNetDevPFGetVF().
(Considering the alternatives, I think
"virNetDevPhysicalFunctionVirtualFunctionGet() would be fairly
horrible... Or what about virNetDevPFVFGet() ?)
We could specify object,action,subject, or we could just say either
ordering of action & subject is valid.
There have been times in the past when any way it was ordered led to
something that seemed nonsensical. I think it would help people like me
who worry over names to have at least a suggestion so that the tie could
be broken in cases where we couldn't make up our mind (i.e. a place to
point the finger when a reviewer questions our choice of name :-)