discuss-gnustep
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

GNUstep Coding Standard Additions


From: Sheldon Gill
Subject: GNUstep Coding Standard Additions
Date: Sun, 24 Apr 2005 12:49:37 +0800
User-agent: Mozilla Thunderbird 1.0 (Windows/20041206)

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







reply via email to

[Prev in Thread] Current Thread [Next in Thread]