[Top][All Lists]

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

Re: GNUstep Coding Standard Additions

From: Adrian Robert
Subject: Re: GNUstep Coding Standard Additions
Date: Sun, 24 Apr 2005 10:35:53 -0400

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

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}
  {block B}

is preferred over

#ifndef REQDEF
  {block B}
  {block A}

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.

reply via email to

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