[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:37:51 -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..
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.
- GNUstep Coding Standard Additions, Sheldon Gill, 2005/04/24
- Re: GNUstep Coding Standard Additions, Benhur Stein, 2005/04/24
- Re: GNUstep Coding Standard Additions,
Adrian Robert <=
- Re: GNUstep Coding Standard Additions, Adrian Robert, 2005/04/24
- Re: GNUstep Coding Standard Additions, Riccardo, 2005/04/25
- Re: GNUstep Coding Standard Additions, Adam Fedor, 2005/04/27
- Re: GNUstep Coding Standard Additions, Richard Frith-Macdonald, 2005/04/28
- Re: GNUstep Coding Standard Additions, Gregory John Casamento, 2005/04/28
- Re: GNUstep Coding Standard Additions, Nicola Pero, 2005/04/28
- Re: GNUstep Coding Standard Additions, Richard Frith-Macdonald, 2005/04/28