RE: class library header file naming and install conventions

["Jeff Hill" <johill@lanl.gov>]

> By Xxxx are you implying that class names start with upper case?
> EPICS seems to mostly have class names start with lower case and 
> use camelCase for compound names, so perhaps the strawman should 
> use xxxYyyy as the example class name.

EPICS was following vxWorks convention in the past -
which was to start all names with lowercase, and to capitalize the
start of each word, when changing to a new word. This was a convention 
adopted originally only for C code, and both C functions and structures 
used this convention.

It's now very common to name all C++ classes (types) starting with a 
capital letter. This seems to be very beneficial in our context
because it distinguishes C++ type names from function names nicely.
I have been naming all C++ classes and types beginning with a capital 
for several years now.

> I'm not sure why the lib directory is needed.

Others have provided the same comment. It seems that we might 
organize subdirectories under $(EPICS_BASE)/src/pdq like this.

option 1: {lib, doc, test, ...} (where lib contains pdq.h, 
					Xxxx.cpp, Xxxx.h, Yyyy.cpp. Yyyy.h)
option 2: {pdq.h, Xxxx.cpp, Xxxx.h, Yyyy.cpp. Yyyy.h, doc, test, ...}

I appears that perhaps more folks prefer option 2.

Jeff
______________________________________________________
Jeffrey O. Hill           Email        johill@lanl.gov
LANL MS H820              Voice        505 665 1831
Los Alamos NM 87545 USA   FAX          505 665 5107

Message content: TSPA

With sufficient thrust, pigs fly just fine. However, this is
not necessarily a good idea. It is hard to be sure where they
are going to land, and it could be dangerous sitting under them
as they fly overhead. -- RFC 1925


> -----Original Message-----
> From: Bruce Hill [mailto:bhill@slac.stanford.edu]
> Sent: Tuesday, March 15, 2011 3:03 PM
> To: Jeff Hill
> Cc: 'EPICS core-talk'; tech-talk@aps.anl.gov
> Subject: Re: class library header file naming and install conventions
> 
> Hi Jeff,
> Thanks for putting together a straw-man on this.   I agree this
> is an important topic and I'm glad you're addressing it.
> I generally like what you've proposed, so I'll just add
> a few comments below.
> 
> Regards,
> - Bruce
> 
> On 03/14/2011 04:11 PM, Jeff Hill wrote:
> > All,
> >
> > When designing a C++ class library whose name is pdq it seems that one
> might
> > implement one header file for every exported class, and follow some
> naming
> > rules.
> >
> > Here is a straw-man. Lots of other schemes are possible, and the only
> really
> > bad scheme is to follow no naming convention at all, I suppose.
> >
> > o The C++ namespace is pdq (class lib names must be all lower case
> letters)
> > o The master header file's name is pdq.h
> > o Each exported class named Xxxx has a header file named pdq/Xxxx.h
> >
> By Xxxx are you implying that class names start with upper case?
> EPICS seems
> to mostly have class names start with lower case and use camelCase for
> compound names,
> so perhaps the strawman should use xxxYyyy as the example class name.
> > o The master header file has '#include "pdq/Xxxx.h"' for each exported
> class
> > o The pdq.h is installed to $(EPICS_BASE)/include/pdq.h
> > o The pdq/Xxxx.h are installed to $(EPICS_BASE)/include/pdq/Xxxx.h
> > o The build system appears to implement this type of install now if, in
> the
> > build area, one has something like src/pdq/lib/pdq which contains the
> header
> > files (where they are installed from). Is that what we want? That
> (redundant
> > pdq in the path) could be initially somewhat confusing to the
> uninitiated,
> > and I don?t see any reason to place the header files in a subdirectory
> other
> > than to avoid changing the build system?
> >
> I have no problem with pdq appearing twice in the path,
> but I'm not sure why the lib directory is needed.
> > o The c/c++ files are named src/pdq/lib/Xxxx.cpp
> >
> Ditto here.    Why not:
> src/pdq/xxxYyyy.cpp
> src/pdq/pdq.h
> src/pdq/pdq/xxxYyyy.h
> src/pdq/doc/pdq.html
> src/pdq/doc/pdq/xxxYyyy.html
> > o The documentation master goes in src/pdq/doc/pdq.html
> > o Maybe the class interface documentation goes in
> src/pdq/doc/pdq/Xxxx.html
> > (same concerns about redundant pdq in the path)
> >
> > All comments appreciated.
> >
> > Thanks,
> >
> > Jeff
> > ______________________________________________________
> > Jeffrey O. Hill           Email        johill@lanl.gov
> > LANL MS H820              Voice        505 665 1831
> > Los Alamos NM 87545 USA   FAX          505 665 5107
> >
> > Message content: TSPA
> >
> > With sufficient thrust, pigs fly just fine. However, this is
> > not necessarily a good idea. It is hard to be sure where they
> > are going to land, and it could be dangerous sitting under them
> > as they fly overhead. -- RFC 1925
> >
> --
> Bruce Hill
> Member Technical Staff
> SLAC National Accelerator Lab
> 2575 Sand Hill Road M/S 10
> Menlo Park, CA  94025