Descriptive Variables, Descriptive Comments, or Both?

[MrKowz]

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]

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]

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]

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]

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]

Never mind

 

[RoryA]

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]

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]

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]

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.