Re: GNUstep Coding Standard Additions

[Gregory John Casamento]

--- Sheldon Gill <sheldon@westnet.net.au> wrote:

> There are some things which don't seem clear from the coding standards.
> 
> This has lead to things being done differently in various places. I 
> think it is a good idea to clean up and standardise.
> 
> Hence, I'm proposing a number of additions/clarifications with the aim 
> to make things clear and consistent.
> 
> Naming
> ======
> 
> There are a couple of naming standards in use. The trouble is that 
> standard GNU form conflicts with standard NeXT and Apple forms.
> 
> For ObjC methods the standard is "verbClause" or "typeInitialiser".
> For ObjC classes the standard is "NSObject".
> 
> Functions, though, are much more ambiguous:
> The NeXT standard is GSFunction() pretty much everywhere.
> The GNU standard is gnu_function().
> Both are followed internally in different places.
> 
> My recommendation is GSFunction() for API entry points and 
> gnu_function_style() for static local functions. This makes it very apparent

I agree with this.

> For ObjC object instances, the issue is less clear but should be 
> "anObject" generally. What if it's a single word? "Object" or "object"?
> 
> I think we should also be clear that "dictionary" or "dict" is preferred 
> over "d". Except for mathematical function implementations single or 
> double character identifiers are a bad idea.
> 
> What about static (ie local) variables? Especially if they refer to a C 
> type rather than an object. Consider
> 
> static int word_count; // GNU style
> static int wordCount;  // NeXT style
> 
> Both methods are used internally. I feel we should standardise on the 
> GNU style.

We should continue to use the NeXT style.   It is the most prevalent in the
code currently.   

I do have one other concern, although it's probably nothing...

When the .gorm or .nib model file loads on GNUstep (or OSX, since the process
is the same there), the establishConnection method is called on all of the
NSControlConnector and NSOutletConnector objects in the model.   An
NSOutletConnector object uses one of two different techniques in
establishConnection to set the variable value depending on how the class was
coded:

1) It looks for a selector which can set the value.  Something like setXXX
where XXX is the name of the outlet (e.g. if you connected to an outlet named
"foo" it would look for "setFoo:").  This is usually what happens in most
cases.

2) If the above selector isn't available, it will fall back to this method and
try to set the variable name directly using the
GSObjCFindVariable/GSObjCSetVariable methods in the runtime.  

For any class which is forced to use option #2, if the outlet name is changed,
the model will have to be modified.   

AppKit classes are very consistent in the sense that they always have the
appropriate setter/getter (so they will use #1, in 99.99999% of the cases).  
So we shouldn't have any problem there, I just wanted to mention the above. 

> Rather than recomment two different styles based on type I think we 
> should use the same style for local objc variables as well.
> 
> Documentation & commenting
> ==========================
> 
> Where should gsdoc comments go?  Mostly, it is in the implementation 
> files. To me, that seems the best place too. However, there are some 
> modules where all the gsdoc is in the header. Others use both, having 
> some in the header and some in the implementation.
> 
> There is no standard in place and I've noticed a few Changelog entries 
> where all the gsdoc is being moved from implementation to header.
> 
> I think that it shouldn't be in the headers. The reason is simple. The 
> implementation and the documentation need to match and keep in sync. If 
> you're editing the implementation, having the documentation right there 
> reminds you immediately of what it's supposed to do. It also makes it 
> easy to keep the two in synch. Mod the code, mod the docs.
> 
> The argument for having docs in the headers is essential ease of finding 
> the function/method prototype and usage information. That is what the 
> library documentation is for. That is precisely why we've got a 
> documentation tool and why we're using markup to make the documentation 
> better and easier to navigate. The real problem here is accessibility 
> and navigation through the docs. Once we have editors that have 
> auto-completion and built-in doc navigation it'll become a non-issue.

I agree with this.

> Conditional compilation
> =======================
> 
> In trying to accommodate differences between platforms and particular 
> build requirements there is a lot of code which is conditionally 
> compiled using the pre-processor.
> 
> I recommend standarising on
> 
> #ifdef REQ_DEF
> 
> instead of
> 
> #if defined(REQ_DEF)
> 
> We should also prefer positive conditional tests over negative ones. Hence
> 
> #ifdef REQDEF
>    {block A}
> #else
>    {block B}
> #endif
> 
> is preferred over
> 
> #ifndef REQDEF
>    {block B}
> #else
>    {block A}
> #endif
> 
> In cases where the conditional block is reasonably large there must be 
> comments at the appropriate points:
> 
> #ifdef REQDEF
>    {block A}
> #else
>    {block B}
> #endif /* REQDEF */

Makes sense.

> In cases where conditional compilations are nested, each preprocessor 
> directive should have a comment.
> 
> Tabs vs Spaces
> ==============
> 
> Its an age old debate but my experience is that tabs confuse things more 
> than they are worth. Many programmer editors today support using the tab 
> key to insert spaces rather than a tab character. They also support 
> block indent/unindent.
> 
> GNUstep uses the GNU 2/4 character indenting convention which doesn't 
> match the use of 8 character indents most of the time.
> 
> So IMHO using tabs isn't particularly convenient. Use of tabs can also 
> confuse searches and diffs.
> 
> Hence, I move that use of tabs be dropped. All in favour?

On the tabs point, agreed.

> 
> Are there other coding standard issues which should be addressed?

Any and all classes, enumerated types, & constants which are GNUstep specific,
should be renamed to start with the GS prefix.  Currently there are only a few
examples of things which violate this (i.e. they begin with NS instead of GS),
but I would like it to be consistent across the board.  The NS prefix should be
reserved for Apple/OpenStep classes ONLY.  This gives a clear indication to
developers what is and is not available on both platforms.  Also all methods in
existing NS classes which are GNUstep extensions of said class should be
clearly documented as such in the gsdoc comments.

Later, GJC

Gregory John Casamento 
-- CEO/President Open Logic Corp. (A MD Corp.)
## Maintainer of Gorm (IB Equiv.) for GNUstep.