[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: GNUstep Coding Standard Additions
From: |
Richard Frith-Macdonald |
Subject: |
Re: GNUstep Coding Standard Additions |
Date: |
Thu, 28 Apr 2005 07:52:55 +0100 |
On 2005-04-24 05:49:37 +0100 Sheldon Gill <sheldon@westnet.net.au> wrote:
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".
Yep.
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.
I try to stick to the GSFunction() style everywhere, and reserve the
underscore for macros.
For ObjC object instances, the issue is less clear but should be "anObject"
generally. What if it's a single word? "Object" or "object"?
Variable names begin with a lowercase letter.
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.
I think the rule is that variables should be clear, readable, and not
misleading ... so it depends a lot on context. In general, shorter is
better as long as it's very obvious what the variable is ... so if a
variables's scope is larger (many lines), it needs to be longer and more
descriptive.
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.
I stick to the NeXT style .... just like functions and classes.
Rather than recomment two different styles based on type I think we should
use the same style for local objc variables as well.
I stick to the capitalised style for all variables, methods, and functions
... very simple.
Capitalizing the initial letter is for classes and public functions.
Documentation & commenting
==========================
Where should gsdoc comments go?
When I wrote the gsdoc stuff, my idea was to put comments in the source code
(rather then headers) so that it's as close as possible to where a
programmer is working while writing and bugfixing, to amke it as easy as
possible for them to add documentation. My theory was that this would mean
that we got more/better documentation, and that this factor overrode any
other issues such as the fact that putting documentation in the header is
the more logical place.
Now, after it's been available for a few years, it seems like I was wrong
(it does not seem to have improved the frequency with which people document
the code), so I regret having made that decision (coding autogsdoc was a
whole lot more complex than it would have been if it only looked at the
headers). If I was going to do it again I'd just put the documentation in
the headers.
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)
If you use defined(X) you can combine it with other checks using logical
operators ... which is much more powerful (and easier to read than nested
#ifdefs, so if yoiu have to have a standard, it should be to use defined()
rather than ifdef
We should also prefer positive conditional tests over negative ones. Hence
Yes, but it's no big deal.
In cases where the conditional block is reasonably large there must be
comments at the appropriate points:
Comments are good.
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?
I have no problem with tabs as long as they are set at the standard, 8
space intervals.
Spaces are definitely better, but people obviously don't notice tabs (as
they are invisible in most editors) ... so it's not clear how much good
setting a guideline would be. However, I'm in favour of using spaces rather
than tabs as a general guideline, since in my experience the correct use of
whitespace and indentation is the biggest readability issue between the
styles of competent programmers.
Are there other coding standard issues which should be addressed?
I hate sounding negative about this ... but I think you are already wanting
to go too far.
1. People should be free to code as they like as long as we keep to a
sufficient degree of consistency for code to be readily readable by everyone
(and I think the code libraries have that degree of consistency).
2. I seem to agree with some of your suggestions, but disagree with just as
many. I suspect other people will feel the same way (probably not with the
same ones).
- 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, 2005/04/24
- 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 <=
- 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