Re: GNUstep Coding Standard Additions

[Richard Frith-Macdonald]

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