Re: GNUstep Coding Standard Additions

[Adrian Robert]

On Apr 24, 2005, at 12:49 AM, Sheldon Gill 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.

Most of your suggestions I agree with.  Comments below on some other 
ones..


> Naming
> ======
> ...
> For ObjC object instances, the issue is less clear but should be 
> "anObject" generally. What if it's a single word? "Object" or 
> "object"?

The latter is standard in Java and should be in ObjC/NeXT/Apple-land.  
Otherwise when you see a method call you don't know if it's a class or 
instance method.  (Among other problems.)


> 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.

For multi-word class names, some people like to use initials, as in

NSDistributedNotificationCenter dnc = ...;

Personally I think this is essentially as bad as single-character 
identifiers and should explicitly be recommended against.


> 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.

In Java, NeXT style is used for these, but since in ObjC they really 
are regular C variables rather than anything OO, perhaps C style is 
better.


> Rather than recomment two different styles based on type I think we 
> should use the same style for local objc variables as well.

Hmm.  Contrasts with the standard for naming object instances.  Are you 
proposing to name object variables using one convention and primitive 
variables using another?  Seems like it might be confusing.  In 
addition, though I can see the argument for marking these differently, 
it loses the marking of class/C variables which I think has better 
potential to reduce errors than marking primitives.


> 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.

As you know this is a long-standing issue.  I don't have a strong 
opinion and agree with your points here for the most part.  You seem to 
be saying that users of the GS APIs should be consulting HTML GSdoc 
whereas developers of the APIs should not have to do either this or 
open up a header file.  I guess this makes sense to some extent.  But 
what about class clusters?  When the impl is in a subclass, the GSdoc 
still has to be in the main source file, right above a '[self 
subclassResponsibility]' line.  This eliminates the developer 
convenience for modifying the gsdoc and moreover might lead to cases 
where GSdoc is accidentally put in the subclass (and never found).  The 
header method keeps everything in the same, known place, and can serve 
as a backup when neither source code nor HTML-ized GSdoc is readily 
available.  Logically, it declares the contract that the implementation 
must live up to.


> 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)

Is there an equivalent for

#if defined(REQ_A) || defined(REQ_B)

in '#ifdef notation'?


> 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

Not sure about this.  Following this convention could sometimes make 
for less readable code.


> Tabs vs Spaces
> ==============
>
> Its an age old debate but my experience is that tabs confuse things 
> more than they are worth.

Fully agree here.