Re: GNUstep Coding Standard Additions

[David Ayers]

Richard Frith-Macdonald wrote:

> On 2005-04-24 05:49:37 +0100 Sheldon Gill <sheldon@westnet.net.au> wrote:
> 

FWIW...  I believe that better specification of coding standards is a
good thing.  I don't have strong feelings either way for most of the
issues mentioned.  But I think we would get a lot more headway in this
subject if we "s/standards/guidelines/" suggesting that we won't
reject/revert patches that do not conform, but that anyone can jump in
and fix these issues as they please.

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

Well I personally would also favor the comments in the implementation
files but mostly because I like to look at headers to get a TOC-like
birds-eye view of the class and in depth documentation obfuscates that.
 OTOH for certain usages (static inlines) there is no implementation
file so for special cases like GSObjCRuntime, I'd rather have the
documentation consistently in the header than scattered in both files.

But I don't feel strongly about it either way.

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

Well then, I claim incompetence!  ;-) No, not a really big issue but I
often deal with varying distributions with varying editors and is always
a pain to get the indentation features set just right.  If we decide on
a standard here I'd be really really be happy if we could simply put
some configuration files for some of the standard editors some place in
cvs that we could copy into the HOME directory and then be done with it.
 I can see if I can come up with something for emacs.

Cheers,
David