Re: How to name variables in a program?

SerGioGio wrote:
> Having a strong convention for naming your variables in your program is an
> important issue often overlooked.
> Can anyone point me to a good source on the web dealing with this issue?

The Java naming convention is pretty good on this. Any symbol with
global scope should follow roughly:


<modulename><Submodulename+><Descriptivenameforsymbol><Subname+><Action>

That is to say, the name of the module where the symbol came from
should prefix the symbol all in lowercase. Then with first letter
capitalization follow it with an option submodule name, and possible
others as necessary. Then just give the name that best describes what
the symbol is with the first letter capitalized, and if there are any
auxilliary names with the first letter capitalized. An action, if
there is one, is placed on the end. For example:

int dbPop3MsgHdrGet (struct pop3Db * db, struct mimeMsgHdr * msg);

Note that the symbols "db" and "msg" do not follow the naming
convention since they are parameters rather than a symbol linking to a
globally available thing. Presumably, you have a module db, with a
sub-module Pop3. "MsgHdrGet" sort of describes what the function is
doing, with "Get" being the action placed on the end.

Types are often not restricted to certain modules (but modules might be
named after them, if a module has the sole purpose of managing a type)
in which case you just drop the module names.

For local symbols, drop the module name and sub-module name (since its
redundant), and make the first character lower case. For
auto-variables within a function drop as much redundancy as possible.
I.e., the function name will often contain within it enough naming
context that naming the local variables with as much detail is
unnecessary.

There are certain conventions for variable names. For integers used as
indexes, the Fortran convention is so common and useful there is no
reason to abandon it. I.e., starting with lower case i, and just
increment from there. For integer variables which measure size end the
variable name with "Sz" after an appropriate name. For integer
variables that measure the quantity of something (except for # of
bytes) end the variable with "Qty".

Constants should be defined with all capital letters, with optional
context or module prefixes and words seperated with underscores.
Example: ERROR_OUT_OF_MEMORY.

Beyond that, try to pick root names which are descriptive as possible
for whatever it is that they symbol is trying to be. This naming
convention is ideal because to the greatest degree possible, just by
looking at the symbol name you can determine what the variable is
trying to be/do and where it comes from. Its also easy to get use to
(unlike the spacing and brace conventions where everyone's idea drives
other people crazy, and never seem to be dictated by practical
considerations; i.e., limited monitor view area and the negative
ergonomics of "scrolling".)

I would also *HIGHLY* warn you against the hungarian notation. That
convention has you naming variables and types redundantly with
information that your compiler and IDE's derive for you for no good
reason. Its conventions also cause you to focus on certain very
low-level primitive characteristics of type definitions. I.e., if
something is a pointer to something, they cause you to prefix with p
(or LP, or some similar abomination) as if this kind of representation
detail is important for you to realize at all times, even though your
compiler will happily give you errors if you were ever to screw that
sort of thing up anyways. Real program design should have you focusing
on higher level considerations for your objects/symbols, etc.

When I was young and naive, I tried to just blindly adopt hungarian
notation for about a week. It was a painful exercise, and at the end
of it, I just instantly ended up throwing away all the code I tried to
write using the notation. It slows you down, and makes the code
unreadable, and truly serves no effective purpose. I'm amazed that
Microsoft managed to write entire applications in this way, and equally
amazed that they actually attempt to maintain them afterwards.

--
Paul Hsieh
http://www.pobox.com/~qed/
http://bstring.sf.net/

.

Relevant Pages

  • Re: Naming of private functions
    ... > Naming conventions are intended to give the reader a way ... > your project the access rights to the symbol make such ... > convention for the functions, ... They can't justify it rationally to me, ...
    (comp.lang.cpp)
  • Re: Naming Standard
    ... The RVBA (Reddick VBA) naming conventions are available ... > Convention, derived from the Leszynski*-Reddick Naming Convention for ... > Microsoft has something on this in the Knowledge Base, ...
    (microsoft.public.access.gettingstarted)
  • Re: great idea -- explain own bids
    ... naming a convention is not illegal, ... give full disclosure. ... experienced players, you can just say "Inverted", the opps nod ...
    (rec.games.bridge)
  • Re: Questions about app design - OOP with python classes
    ... It's unreliable in the sense that the coder has to follow the naming ... convention, and must have some bare minimum of sense. ... I'd have expected the compiler to handle the conversions through casts ...
    (comp.lang.python)
  • Adding new users and default naming
    ... Where can I configure SBS2003 so when I add a new user it uses a naming ... convention of first letter of first name and then last name. ... Tony ...
    (microsoft.public.windows.server.sbs)