Re: GNUstep Coding Standard Additions

[Nicola Pero]

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

Ahm ... yes, single or double character identifiers are very difficult to
search/replace, and are generally obscure/unreadable.

But to make them better, the best thing is to replace them with meaningful
(self-commenting) names.  Eg, 'threadLocalDictionary' instead of 'd'.  
'dict' is not much of an improvement over 'd'.

Still, stuff like 'i' or 'd' make sense for loops or temporary variables
used shortly when it's very clear what they mean.  In those contexts they
might even be easier and clearer to read.

I think you should never have more than 1 or 2 of such temporary variables
though ... if you have more you need to give more meaningful
(self-commenting) names else it gets confusing ;-)

All this is very much un-formalized, probably we shouldn't have anything
about that in our coding standards.  After all, the GNU coding standards
already say that variables should have meaningful names (I think/hope it
says that), and that's really all we need. :-)


> Where should gsdoc comments go?  Mostly, it is in the implementation 
> files.

There are different opinions on this matter ... ;-)

Some people don't use autogsdoc and they just read headers. :-)

Eg, I tend to do that for third-party libraries when I don't have time to
figure out how/if their customized documentation system works and/or
where/how I can get the documentation.  The headers are always in the same
place for all software, and they are guaranteed to contain the function /
symbol you're looking for.  If they also contain comments on what those
are supposed to do, bang!, in no time you're on your way to fix things.

Also, it seems like this is one of the few things that C gets right: you 
have a public header file declaring the API, and a private implementation 
file implementing it which is compiled and turned into object code.

So the documentation of the public API should go in the public header 
file, while the documentation of the private implementation should go in 
the private source file.

I suppose it's mostly up to the people writing the documentation though
(not me at the moment).  Anyway as a user I vote for having it in headers. 
:-)

Thanks