This thread focuses on naming or defining variables appropriately when you program code. This is commonly viewed as an unimportant aspect that we reluctantly do just to get on with our program. Sometimes we never consider what others might first think upon reading a particular variable. Hopefully, you will attain a different view and practice of naming variables once you read this tutorial.

Why It’s Important

Have you ever named a variable something completely irrelevant to its primary function? Perhaps you wanted to light an LED and called the output port TNT or Top_Secret. This might be quite sufficient for your purposes, but if you ever share your code with someone else or ask for help they probably would have no clue as to what it is for. In fact, you might not even recognize it yourself after a couple years. Therefore, you should always attempt to name or define your variables that suggest their obvious function in your code.

Advice On How to Get Started

One of the first pieces of advice has been already mentioned; that is, naming your variables according to their fundamental purpose. A common misconception of categorically naming variables is how long or short you should entitle them. It is recommended that you do not inhibit the length of a variable, otherwise it will result in a misunderstanding of their function. Complex names or numerical signs aren't advised, since it might impede comprehension. Your variables should be simple and straight to the point.

Another important concept to remember is how our brains organize information and what triggers our memories. Now this is where it gets very interesting! As you continue to practice naming variables, your brain commences organizing the names with their significance. What exactly does that mean? Well, let me provide an example.

First let’s consider that variable we previously decided to symbolize our I/O port going to an LED. As part of our application, the LED will continuously blink to inadvertently represent a sophisticated security system that will keep predators away by bluffing. After contemplating on the hardware and requirements for our simple application, we come to the conclusion that only one LED is required for an effective solution. Therefore, we could name our variable simply as LED, but only due to the fact that one LED is being used. If this is your first coding project and you need assistance, then whoever is helping you can automatically connect with what you are doing by using that variable name. The name implies that you are controlling an LED as part of your hardware on your I/O pin. To confirm this assumption, anyone who is helping you can quickly glance in your #define section and see whether you set it as your output port (TRIS or GPIO, depends on PIC). If you had used the name TNT, a person’s brain wouldn’t emphasize remembering that name in association with its function because it’s completely irrelevant.

Triggers

If you wanted to remember a meeting you have at 12:00 PM, you can think of “noon” or “lunch” to prompt a trigger. Whenever you think of those words, it will effectively stimulate a thought that indicates you have a meeting at that time. Therefore, try to organize specific triggers that might stimulate thoughts relevant to your variable name. This is a useful trick when you adjust your code in the future; since you will be more likely remember the variable names and what they do. Likewise, try to think of variable names that might trigger accurate functions in your code so that others may easily understand it.

Now you see how important it is to appropriately and effectively name your variables, for your benefit and for other people’s as well.

Any suggestions, comments, or advice is encouraged!

 

http://en.wikipedia.org/wiki/Naming_convention_%28programming%29
http://en.wikipedia.org/wiki/Hungarian_notation
http://stackoverflow.com/tags/naming-conventions/faq
http://www.joelonsoftware.com/articles/Wrong.html

Interesting reads.

 

I'm a big fan of programmers using good, descriptive names for variables, functions, and objects. I've worked on projects with non-native English speakers and I modified a utility I wrote a decade or so ago to spell-check token names, even ones made from compound words with underscores or camel-case. It's the xref.zip file here; you'll need a C++ compiler to build it unless you're willing to use the Windows exe packaged with it (I wouldn't in today's risky computing environments). It's also useful to folks who aren't as good at spelling as they'd like to be.

Here's a chunk from the man page:

NAME
    xref - produce a cross reference of tokens in a set of text files

SYNOPSIS
    xref [options] [file1 [file2...]]

DESCRIPTION
    Tokens are gotten by replacing non-alphanumeric characters by
    space characters, then parsing on whitespace.  The output is
    printed to stdout and is the token on its own line followed by the
    files and line numbers that contain that token.  The -t option
    causes only the tokens to be printed out, one per line.

    The program is also capable of spell checking the text files.  You
    may compile in the location of a default dictionary to use.  A
    dictionary is a list of tokens separated by whitespace that give
    the correct spelling of the tokens.  Letter case is ignored.
    Any misspelled tokens are printed to stdout.

    During spell checking, the program will parse compound tokens such
    as 'MyFunction' and 'my_function' into the tokens 'my' and
    'function', then look them up in the dictionary.  This allows
    programmers to help ensure they're using descriptive names for
    symbols in their programs.  The algorithm for splitting a compound
    token is to replace underscores by space characters, then put a
    space character before each upper case letter.  Single letters as
    tokens are ignored.  Tokens that are misspelled are printed to
    stdout.  The program includes a built-in dictionary for keywords
    in C, C++, python, and shell programming.  Tokens that begin with
    '0' are ignored, as they are likely octal or hex constants.
    Tokens that are composed of all digits are also ignored.

    In the source code, you can define a default dictionary to use for
    spell checking (if the string is empty, no default dictionary is
    used).  It is not an error if this file is not present.

    Because of the algorithm used for splitting composite tokens,
    tokens with all uppercase letters will be ignored when spell
    checking.

If you are willing to use the exe because you don't have a C++ compiler, note that the default dictionary string has many spaces after it. This lets you change the string in the executable; just use an editor that can edit binary files (vim or emacs work fine).

 

Thanks for the contribution to this thread! Any further input on this is encouraged.

 

Usually I use the three first letter in the variable name, as a descriptor of what kind of value it is supposed to hold. Integer, char, float...

For example:

intTimeToGoHome = 15
intNow = 7
intTimeLeftAtWork = intTimeToGoHome - intNow

It is very important to me, that after a few month, I am able to read my own code, and understand what it does. Guess this should be important to all programmers. Regardless of what level they are on, novice to experts.

 

[...]Guess this should be important to all programmers. Regardless of what level they are on, novice to experts.

...or perhaps not. Let's suggest that after three weeks you decide to change definitions of some variables from int to short. What would you do - run s/intNow/shortNow on all files? What about platform-dependent types like ssize_t, uintptr_t, ino_t? What if you need variable of specific length and use int32_t, uint8_t and alike?

Usually when I read code remembering what integer type a variable is has very little effect on understanding. Mixing integers, pointers and aggregate types may be much more annoying.

 

...or perhaps not. Let's suggest that after three weeks you decide to change definitions of some variables from int to short. What would you do - run s/intNow/shortNow on all files? What about platform-dependent types like ssize_t, uintptr_t, ino_t? What if you need variable of specific length and use int32_t, uint8_t and alike?

Usually when I read code remembering what integer type a variable is has very little effect on understanding. Mixing integers, pointers and aggregate types may be much more annoying.

I guess I would have to take the job and change them.

Point taken.

 

Usually I use the three first letter in the variable name, as a descriptor of what kind of value it is supposed to hold. Integer, char, float...

This is usually called Hungarian notation and has lost favor, at least in the industrial world and at least for denoting type. One reason is, as alluded to, the maintenance problems it causes. And a programmer should be using a good editor or IDE that can show him the type of the argument as needed. In fact, if you have to search a ways for the definition of a variable, then your functions are probably too big anyway (i.e., poor programming practice). You shouldn't be using globals if you can help it. Use a tool like ctags to help you find function definitions if you're not using an IDE. When I work on UNIX-type boxes, I have a cron job run ctags on /usr/include and other directories every night so I have a fresh tags file for the things I might want to look at.

There is one area where this Hungarian notation can be useful and that is to help differentiate semantic or architectural things, rather than purely syntactical things like a variable's type. For example, a leading name of "strm" might denote something that deals with a stream in the system and this could help programmers understand which subsystem in the codebase was involved. Another area it's used in is to reduce namespace pollution if you're working with a language that doesn't have namespaces.

 

.......................................................