GNUstep Coding Standard Additions

[Sheldon Gill]

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

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.

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.

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 */

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?


Are there other coding standard issues which should be addressed?


Regards,
Sheldon