# Descriptive Variables, Descriptive Comments, or Both?



## MrKowz (Jun 21, 2011)

Time for the weekly ponderable!

In your coding practice, what do you prefer?  Do you create descriptive variables such as "HideCount" to count the number of rows hidden; "Delim" to serve as a delimiter; etc.  Or do you create simple, nondescriptive variables and create a block of comment(s) that describe what each variable is?

Eg:

```
'Variable Declaration
'    h = Number of Rows Hidden
'    d = Delimiter string
Dim h As Long
Dim d As String
```
Or do you prefer to do a hybrid of the two?

Personally, I like to use descriptive variables (even though it can make some lines seem decently long).  I find it makes it easier to go back and debug/review code.  When it is one-off code, I still tend to use descriptive variables; but on larger code that has quite a few variables (usually over 10 or so), I will also write a block of comments to describe the variables.


----------



## Greg Truby (Jun 21, 2011)

If we're talkin' "fall-off-a-stump" kinda simple, i.e. a stand-alone procedure with naught but a handful of lines and something that will be short-lived then I might opt for one-letter variables.

If it's anything more than than I use my own variation on Gregory Reddick's implementation of the Hungarian (Simonyi) naming conventions. Reddick's standards are found here: http://www.xoc.net/standards/rvbanc.asp

Within a procedure, I will alphabatize the variables to make them easier to find.

```
Dim dblVersion          As Double, _
        dblVrsnRecommend    As Double, _
        eVrsnResult         As ge_VrsnResults, _
        lngErrNum1          As Long, _
        rngTLC              As Excel.Range, _
        strTemplateFullName As String, _
        wsTemplate          As Excel.Worksheet
```
Furthermore, in any project I do, I have a boilerplate module that I drop in that explains my naming conventions in case someone else ever has to support my code.

```
' ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
' GENERAL CODING NOTES
' _____________________________________________________________________________
' ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
' module:   basZZ_GeneralCodingNotes
'
' revised:  Aug 2008
'
' author:   Greg Truby
'
' summary:  This module contains no code, only comments.  The notes here
'           are not project specific.  They are general notes on my coding
'           conventions and practices and this same boilerplate module
'           should be found in any project I develop.
' _____________________________________________________________________________
' ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
' coding conventions
' ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
'   a.  Variable prefixes
'
'       i. types:
'           •   "g_" = globals     "m_" = scoped to the module
'           •   "c_" = constants   "e_" = enumerations
'           •   "s_" = statics     "u_" = user defined types
'
'       ii. leave only one underscore if concatenating prefixes
'           •   "gc_"
'           •   "me_"
'
'   b.  Arrays or Collections are shown by using variable names that are
'       plural are instead of an "a" prefix.  Some collections may use
'       a "col" tag.
'
'   c.  Tags
'
'       i. tags for common types of variables
'
'           bar office.commandbar               int integer
'           boo boolean                         lbl msforms.Label
'           btn msforms.commandbutton           lbx msforms.listbox
'           byt byte                            lng long
'           cbx msforms.combobox combo-style    mpg msforms.multipage
{notes go on for another 120 lines}
```
 
Whatever convention you decide to use - make it intuitive and make it a habit. You have no idea how foreign your own code can look when you come back four, five or six years later. Using a naming convention is a tremendous help in deciphering your own code. And it's essential if you want others to understand your code. I know that if a member posts a question here that has a fair amount of code and the variables' names are all higgledy piggledy, I'll just skip the post rather than spending 20 minutes just trying to untangle the variables' meanings.

I should add that there isn't any kind of a global standard for this.  And since most VBA coding is done outside of an IT dept's domain, there's probably not a standard naming convention for Excel apps inside most companies.  And you'll hear some folks make the argument that tags that explain a variable's type are really obsolete.  That may be - but I still like to know if I'm dealing with a range or a string.  Am I dealing with a range or a double or a variant?  Am I dealing with a collection or an array?  So for my own sanity, I _like_ using a tagged naming convention.  But it's a rather subjective subject.


----------



## VoG (Jun 21, 2011)

I'm terrible 

I grew up on Fortran IV in the seventies. Variables I to N were by default Integers (~VBA Longs). So I tend to use those for integers, LR for last row, X for pretty much anything else.

AND I don't document anything - well just the odd bit of code that I thought was 'outstanding' which I save - not much of that however


----------



## shg (Jun 21, 2011)

I use the declaration line to describe usage:

```
Function AlignKeys1(wks As Worksheet) As Boolean
    Dim rKey        As Range    ' cells in header row containing the first column of each dataset
    Dim cell        As Range    ' For Each loop control variable
 
    Dim iRow        As Long     ' row index
    Dim iCol        As Long     ' column index
    Dim aiCol()     As Long     ' array containing the column indices of Keys
 
    Dim ar()        As Range    ' an array of ranges containing each of the datasets to be aligned
    Dim iRng        As Long     ' index to range array
    Dim nRng        As Long     ' number of ranges
 
    Dim ab()        As Boolean  ' "is not least" Boolean array
    Dim rRow        As Range    ' one row of rKey
    Dim rInt        As Range    ' cells in a given dataset range to be pushed down
    Dim rIns        As Range    ' union of the rInt's; range to be pushed down
```


----------



## TinaP (Jun 21, 2011)

I use a mish-mash of naming conventions/comments and Greg is right, troubleshooting my code is like herding cats.  (I once had to modify a huge procedure and ended up rewriting the entire thing because it would be easier.)  As I get more coding experience, I'm shifting more and more to my own version of Hungarian variable names and lots of meaningful comments.  

Also, I'm writing code in modules so that I can just insert a module into a workbook and run with it. The next time I need to import data, I just copy that module into the workbook and I'm done. Theoretically, each module is written and commented properly, so there will be no confusion in the future. 

I really like Greg's boilerplate module to explain naming conventions, though. I'm going to have to try it.


----------



## JazzSP8 (Jun 22, 2011)

Never mind


----------



## RoryA (Jun 22, 2011)

Descriptive variable (and routine) names, unless the variable is just a counter for a loop when I do tend to use i, j and n; very little commenting unless I'm spelling something out in a forum answer.


----------



## Domski (Jun 22, 2011)

These days in general I try to be good and steer clear of non-descriptive variables or even ones like myRange, myShape. It depends on the audience as to whether I put comments on. As I pretty much only write code for forums or my own use I don't tend to comment it unless the OP asks for an explanation. Stuff I have written for other people at work is pretty good on both accounts though.

Dom


----------



## MrKowz (Jun 23, 2011)

Lots of nice ideas in here.  I really like Greg's approach for the more elaborate procedures.  I've already semi-stolen his way of dimming variables (In the vertical, columnar, fashion); I might have to semi-steal his naming convention too.

Shg's approach is nice for the smaller procedures - short variable names that at least somewhat describe what the variable is meant for.

Cheers!


----------



## cornflakegirl (Jun 24, 2011)

I use a version of the Hungarian naming convention, and a fair number of comments. I always comment if I've nicked a bit of code from someone on here - including the thread URL.


----------



## xenou (Jun 24, 2011)

You don't need to dim variables at all in vba ... I believe you can use _x_ for everything.  Or _x_ and _xx_ if you need two.


----------



## Darren Bartrup (Jun 27, 2011)

I generally use a bag of scrabble letters.  I just stick my hand in, pull out four or five and use them.  Of course, for the more complicated variables I may pull out up to ten letters.


----------



## litrelord (Jun 28, 2011)

Descriptive variables as much as possible here with comments if it's not immediately obvious although I also use l, i and n for loop counters. 

I'm currently working my way through some inherited code which has non-descriptive variable names (some are mildly descriptive but using Spanish or French words instead of English - for no other reason than to try and appear edgy I believe). There's no Option Explicit and when I add it i find many variables that haven't been declared and often I get half way through a procedure and find another chunk of Dim statements (where the code was copied and pasted without being re-written). It's horrible yet strangely satisfying to get each module re-written, commented, variables declared and code optimised. 

Nick


----------



## MrKowz (Jun 28, 2011)

litrelord said:


> Descriptive variables as much as possible here with comments if it's not immediately obvious although I also use l, i and n for loop counters.
> 
> I'm currently working my way through some inherited code which has non-descriptive variable names (some are mildly descriptive but using Spanish or French words instead of English - for no other reason than to try and appear edgy I believe). There's no Option Explicit and when I add it i find many variables that haven't been declared and often I get half way through a procedure and find another chunk of Dim statements (where the code was copied and pasted without being re-written). It's horrible yet strangely satisfying to get each module re-written, commented, variables declared and code optimised.
> 
> Nick


 
I agree, getting code rewritten in a bit more of a logical sense does feel a lot better (and the code most usually will run a lot better).  One of my little pet peeves is when I see variables dimmed somewhere in the middle of code.  There is no reason why it can't be dimmed with the other code!  It shouldn't have to sit all alone, in the middle of the code, with no other variables to play with.


----------



## xenou (Jun 29, 2011)

I *thought* I used a lot of i,j,a,b,s,t,x variables (I do for many short subs and functions).  Inspecting my more serious projects shows more descriptive variables with hungarian notation, and sometimes Types or Classes.

I do like the precise, abbreviated logic of one letter variables and find it's easier to read - most of my short routines use them, and even longer ones.  But I comment my code fairly extensively, and try to keep the procedures discrete so that variables are local and short lived, as much as possible.  True, it's perplexing at first.  But with some familiarity you start to see the logic (I always think of Jindon's code in this regard - at first, quite a puzzle, but with time I see the patterns and start to "get it").

On the subject of variables dimmed in the middle of code ... I *do* rather like the idea of block-level scope.  We could make use of that (I think VB.Net has it now, but not VBA ... someone correct me if I am wrong).

ξ


----------



## BrandonWLH (Jul 8, 2011)

I personally like to stick somewhat to the hungarian style created for c++ or what ever they called it.  You use a small descriptor before vars, functions or callbacks to let you know what it controls.  so btnName for a script which controls a button, txtbName for a text box control, iName for an integer var, pName for private data in a class, strName for a string etc.


----------



## Smitty (Jul 9, 2011)

I think I'm somewhat like Greg (but no where near so precise) in that I declare everything up front.


I can't stand variables declared in the middle of something.

And like Brandon, I use descriptors as well.


----------



## repairman615 (Jul 15, 2011)

Great stuff here!


I am kinda new at VBa. I have seen "str*?" many times in other posts as a var. name, yet untill I read this thread it never clicked str stood for string. 


I am liking the neat appearance by lining them up like Greg (thanks for the Hungarian Link btw), but I am still trying to pick up on writing 'good' code so naming a var. I don't need is a bit trivial. 

For me, I am trying to improve and this thread has already helped the appearance of recent code. But, I will still pull one out when I don't know any better. 

-Jeff


----------

