Naming Your Variables

Discussion in 'Programmer's Corner' started by ELECTRONERD, Dec 12, 2010.

  1. ELECTRONERD

    Thread Starter Senior Member

    May 26, 2009
    1,146
    16
    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!
     
  2. tyblu

    Member

    Nov 29, 2010
    199
    16
  3. someonesdad

    Senior Member

    Jul 7, 2009
    1,585
    141
    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:
    Code ( (Unknown Language)):
    1.  
    2. NAME
    3.     xref - produce a cross reference of tokens in a set of text files
    4.  
    5. SYNOPSIS
    6.     xref [options] [file1 [file2...]]
    7.  
    8. DESCRIPTION
    9.     Tokens are gotten by replacing non-alphanumeric characters by
    10.     space characters, then parsing on whitespace.  The output is
    11.     printed to stdout and is the token on its own line followed by the
    12.     files and line numbers that contain that token.  The -t option
    13.     causes only the tokens to be printed out, one per line.
    14.  
    15.     The program is also capable of spell checking the text files.  You
    16.     may compile in the location of a default dictionary to use.  A
    17.     dictionary is a list of tokens separated by whitespace that give
    18.     the correct spelling of the tokens.  Letter case is ignored.
    19.     Any misspelled tokens are printed to stdout.
    20.  
    21.     During spell checking, the program will parse compound tokens such
    22.     as 'MyFunction' and 'my_function' into the tokens 'my' and
    23.     'function', then look them up in the dictionary.  This allows
    24.     programmers to help ensure they're using descriptive names for
    25.     symbols in their programs.  The algorithm for splitting a compound
    26.     token is to replace underscores by space characters, then put a
    27.     space character before each upper case letter.  Single letters as
    28.     tokens are ignored.  Tokens that are misspelled are printed to
    29.     stdout.  The program includes a built-in dictionary for keywords
    30.     in C, C++, python, and shell programming.  Tokens that begin with
    31.     '0' are ignored, as they are likely octal or hex constants.
    32.     Tokens that are composed of all digits are also ignored.
    33.  
    34.     In the source code, you can define a default dictionary to use for
    35.     spell checking (if the string is empty, no default dictionary is
    36.     used).  It is not an error if this file is not present.
    37.  
    38.     Because of the algorithm used for splitting composite tokens,
    39.     tokens with all uppercase letters will be ignored when spell
    40.     checking.
    41.  
    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).
     
  4. ELECTRONERD

    Thread Starter Senior Member

    May 26, 2009
    1,146
    16
    Thanks for the contribution to this thread! Any further input on this is encouraged.
     
  5. nerdegutta

    Moderator

    Dec 15, 2009
    2,515
    785
    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:

    Code ( (Unknown Language)):
    1.  
    2. intTimeToGoHome = 15
    3. intNow = 7
    4. intTimeLeftAtWork = intTimeToGoHome - intNow
    5.  
    :)

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

    New Member

    Dec 14, 2010
    5
    1
    ...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.
     
  7. nerdegutta

    Moderator

    Dec 15, 2009
    2,515
    785
    I guess I would have to take the job and change them.

    Point taken.:)
     
  8. someonesdad

    Senior Member

    Jul 7, 2009
    1,585
    141
    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.
     
  9. maxpower097

    Well-Known Member

    Feb 20, 2009
    795
    388
    .......................................................
     
    Last edited: Jan 16, 2011
Loading...