[libvirt] [PATCH v3] Document preferred naming conventions

[Daniel P. Berrange]

On Fri, Mar 10, 2017 at 03:31:29PM +0100, Michal Privoznik wrote:
> On 03/06/2017 12:09 PM, 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 v3:
> >  - Clarify function naming wrt verb & subject
> >  - Simplify macro naming, since in practice libvirt code doesn't follow any
> >    rules consistently aside from having a VIR_ prefix.
> > 
> >  HACKING              | 80 ++++++++++++++++++++++++++++++++++++++++++++
> >  docs/hacking.html.in | 93 ++++++++++++++++++++++++++++++++++++++++++++++++++++
> >  docs/hacking2.xsl    |  4 +++
> >  3 files changed, 177 insertions(+)
> > 
> 
> 
> > +*Function names*
> > +
> > +All functions should have a 'vir' prefix in their name, followed by one or
> > +more words with first letter of each word capitalized. Underscores should not
> > +be used in function names. If the function is operating on an object, then the
> > +function name prefix should match the object typedef name, otherwise it should
> > +match the filename. Following this comes the verb / action name, and finally
> > +an optional subject name. For example, given an object 'virHashTable', all
> > +functions should have a name 'virHashTable$VERB' or
> > +'virHashTable$VERB$SUBJECT". e.g. 'virHashTableLookup' or
> > +'virHashTableGetValue'.
> > +
> 
> This will create some functions with ridiculously long names.
> qemuDomainSnapshotPrepareDiskExternalOverlayInactive() for instance.
> Should we lift our "80 chars per line" rule? Say to 100? Even more so
> since we all are working on wide screen monitors (RIP 4:3).

NB, these are naming guidelines not rules, so I'd say it is fine to
adapt to a better short name, if the guidelines would result in such
a ridiculously long name.

Regards,
Daniel
-- 
|: http://berrange.com      -o-    http://www.flickr.com/photos/dberrange/ :|
|: http://libvirt.org              -o-             http://virt-manager.org :|
|: http://entangle-photo.org       -o-    http://search.cpan.org/~danberr/ :|