Re: [libvirt] [PATCHv2 1/1] include: function parameter names same in declaration

----- Original Message ----- > From: "Bjoern Walk" <bwalk(a)linux.vnet.ibm.com&gt; > To: "Daniel P. Berrangé" <berrange(a)redhat.com&gt; > Cc: "Chris Venteicher" <cventeic(a)redhat.com&gt;, libvir-list(a)redhat.com > Sent: Tuesday, February 13, 2018 5:03:40 AM > Subject: Re: [libvirt] [PATCHv2 1/1] include: function parameter names same in declaration > > Daniel P. Berrangé <berrange(a)redhat.com&gt; [2018-02-13, 09:47AM +0000]: > > On Mon, Feb 12, 2018 at 03:24:03PM -0600, Chris Venteicher wrote: > > > Headers use same function parameter names as definition code. > > > > > > In some cases in libvirt-domain and libvirt-network an > > > established > > > naming pattern in the header files was more consistent and > > > informative > > > in which case the implementation was modified in the c file. > > > > > @@ -1626,11 +1626,11 @@ int > > > virDomainInterfaceStats (virDomainPtr dom, > > > */ > > > # define VIR_DOMAIN_BANDWIDTH_OUT_BURST "outbound.burst" > > > > > > -int virDomainSetInterfaceParameters > > > (virDomainPtr dom, > > > +int virDomainSetInterfaceParameters > > > (virDomainPtr domain, > > > > Hmmmm, I kind of expected that "dom" would be more popular than > > "domain", > > but I see the results are somewhat contradictory. > > > > If we just consider the header file > > > > $ git grep "virDomainPtr dom" include/libvirt/libvirt-domain.h | > > wc -l > > 167 > > $ git grep "virDomainPtr dom" include/libvirt/libvirt-domain.h | > > grep "virDomainPtr domain" | wc -l > > 99 > > > > So dom==68, domain=99 => 2:3 > > > > But if we consider the source as a whole > > > > $ git grep "virDomainPtr dom" | wc -l > > 1863 > > $ git grep "virDomainPtr dom" | grep "virDomainPtr domain" | wc -l > > 675 > > > > So dom=1188 domain=675 => 2:1 > > This is biased because for a temporary variable an abbreviated name > 'dom' is preferable, especially if you have an argument 'domain'. > > Since function declarations serve some kind of documentation purpose, > I'd prefer the full name 'domain'. It reads so much better in my > opinion > and characters are cheap. > A little more background ... I have only submitted the changes for include/libvirt/*.h so far. At the bottom is a list of the files impacted by a total of 286 changes suggested by the clang-tidy filter. The focus here is only the horizontal relationship establishing consistency between definition and declaration, not the vertical line relationship of consistency between function definitions. function_definition_1(p1, p2, p3) ---> function_declaration_1(p1,p2,p3) | | | function_definition_2(p1, p2, p3) ---> function_declaration_2(p1,p2,p3) | | | function_definition_n(p1, p2, p3) ---> function_declaration_n(p1,p2,p3) My guess is > 90 percent of the 286 changes make the declaration better. Probably < 10 percent of the 286 changes make the declaration slightly less readable (ex. domain->dom). All of the changes make the declarations consistent with the definitions. None of the changes make the function_definitions worse.