[libvirt] [PATCH v2] Document preferred naming conventions

[Laine Stump]

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 :-)