discuss-gnustep
[Top][All Lists]
Advanced

[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 <address@hidden> 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).





reply via email to

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