Business object coding conventions

[Rich Johnson]

On Tuesday, December 7, 2004, at 03:31 PM, Derek Atkins wrote:

> Rich Johnson <rjohnson at dogstar-interactive.com> writes:
>
>> I haven't seen the following spelled out, so I thought I'd take a stab
>> at it.  It seems to reflect the general coding standards currently in
>> effect for the business objects.
>>
>> For any given business object the following applies:
>>
>> There exist three files for each <object>:
>>    - gnc<object>.h - declaring the public interface
>>    - gnc<object>P.h - declaring additional object management methods
>> not for client use.
>>    - gnc<object>.c - implementing the object
>>
>> The implementation is confined to gnc<object>.c, including the
>> defininition of struct  _gnc<object>.
>>
>> Client code #includes only  gnc<object>.h.  The client is aware only
>> of the datatype Gnc<Object>, defined as "typedef _gnc<object>
>> Gnc<object>".  The client only deals with an unspecified structure via
>> pointer--it remains blissfully unaware of _gnc<object>'s internal
>> structure.
>>
>> Did I get it right?  Should this sort of stuff be contributed to the
>> devel wiki?
>
> Yes, you got it right, but I don't think this is at all necessary to
> get documented beyond that.  It's pretty much "opaque object
> programming 101".  This usage is even documented in the files
> themselves, so I dont really think it needs anything beyond that.
>

Hey, I'll take my victories where I can get them :-)

However, I will quibble with the 'documented in the files' part.  
What's there is pretty skimpy.  FWIW, I'm a fan of _explicit_ 
declaration of conventions and expectations.  I've spent far too much 
time chasing down bugs ultimately attributable to misunderstood 
assumptions.

  AFAIK the conventions used are implicit and not documented, either in 
the code or elsewhere.  The 'private' aspect is documented  only in a 
few of the *P.h headers and the absence of any 'public' declarations 
implies public unless specified otherwise.    I agree that the pattern 
used for the most part matches that of basic opaque object programming 
(aka data abstraction/hiding for C)--but it isn't stated anywhere.

But now it's on the record;  so I'm happy  :-)

There're also _two_ naming conventions at play:  the aforementioned 
StudlyCap  "*P.h",  and the "*-p.h" convention used for qof* objects.  
The use of one or another appears to be historical.   Is one preferred 
over the other for new work?  Or should one stick to the predominate 
convention for the directory at hand?