[Tinycc-devel] naming conventions

[Gregg Reynolds]

I submitted some documentation to Rob offlist, which lead to a
discussion that really should be onlist, so here goes:

The topic is naming conventions.  There are two specific issues:

tcc uses global vars with names like ch, file, tok for the most
recently handled thingee.  This is not so good, since such names are
also often used in local environments, and they're not especially
descriptive.  My suggestion was to use a prefix "tcc_" for all of
them.

Rob's response:

> Although tcc_ is easier to grep for, it provides no useful information.  The
whole project is tcc.  There isn't any symbol in the project you _couldn't_
prefix with tcc, so it does nothing to distinguish them.

To which I answer:  we're talking about conventions.  You can prefix
any symbol with anything.  The idea is "tcc_" means "I'm a global
name",  that's all.  It's a namespace identifier, not a semantic
element.

> In this case, ch is the char most recently read from the file.  I just 
> renamed it to "fch" which is at least something I can grep for.  Might rename 
> it to something longer later, but I'd rather group the globals into a struct 
> or
something, if that won't impact runtime performance...

To which I answer:  a struct would be best from the readability
standpoint; it might involve a slight performance hit, but it would
probably be pretty easy to measure.  Otherwise, I like the leading
underscore convention, by which I mean interpreting a leading
underscore to mean "I'm a special implementation thingee".    A prefix
like "tcc_" or "g_" (for global)  or even "_ch" just says "I'm special
and I'm global"; I don't see much need for more information in these
names.  It's pretty easy to remember that a global named tok is the
most recent token, or that a global named ch is the most recently read
char, so something like "fch" strikes me as likely to confuse - what
was it that "f" means again? In fact, it's pretty much guaranteed to
confuse, since the notion of a lookahead ("following char = fch?") is
part of the domain knowledge.  I'm afraid I don't like fch much at
all.  Sorry.

If you want to make the meaning explicit you need to have a real name,
like most_recent_char_read, prefixed with the global prefix.  Or you
could use an acronym like "mrch" so long as it is clearly documented.
But in  a compiler, where you know you have most recently handled
chars, tokens, etc., I think "ch" with global prefix suffices.  In
other words, a certain amount domain-specific knowledge can be assumed
(but should still be documented.)

The second issue is using suffix _t for type names.  I tend to favor
it - I consider "size_t" to be more expressive than "size" (explicit
is good).  Rob isn't so crazy about this since it can be considered
redundant - syntax tells you that an identifier is being used as a
type name.  I'm not religious about it, except where a type is itself
used to encode type information.  E.g. we have a variety of token
types, and the global int tok encodes the type of the latest token,
and "int v" is often used for a token type code.  In this case I favor
"typedef int tok_t" pretty strongly; foo(tok_t tok) is much more
expressive than foo(int v), in my opinion.  In any case, if you're
going to use a typedef at all (which I strongly favor), you have to
pick a naming convention of some kind.  If you do "typedef int tok;"
then you can't use tok as a var name.  The _t suffix is the most
concise and expressive way I know of to do this, plus it's widely used
and understood.

Opinions?

gregg