Re: GNUstep Coding Standard Additions

[Sheldon Gill]

Nicola Pero wrote:
> > 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'.

We're basically of a mind here. I was try to say 'd' should be right 
out. 'dict' fine if it's the only dictionary you could be possibly 
talking about and the context is limited to around 10 lines or less.

Longer, more literate names are recommended at all times.

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

That's why I noted the exception for well-known/accepted mathematical 
usage. The i for array/vector sub-scripts certainly qualifies.

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

There is a section which is more guide than standard and it was in there 
that I thought of adding these sort of notes and recommendations.

> > 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. :-)
[snip]
>
Hmm.. to paraphrase, you prefer headers over other systems because:

(a) the customised documentation system isn't immediately apparent

or

(b) the docs aren't immediately locatable

is that right?

So, if you have nice docs which were easily located it would be a 
non-issue for you? Especially if the docs were easily navigable from 
your editor/ide?


Regards,
Sheldon