Terminology and Style Guide - hecon5/msaccess-vcs-addin GitHub Wiki

This page contains style and terminology for how to describe elements within the Wiki, Code, and Interface for a consistent approach.

This is a constant work in progress, and is not complete. Items added here were added for clarity where a universal consensus may not exist.

Use active voice for documentation.

Where not found here, use of Google's Style Guide is generally accepted; though some deviations from their guide have been made in favor of other methods where appropriate.

Action / Descriptor Terms

The following are either excerpted or differ from the above style guide. Use these methods first. If you don't find what you need here, go to the above guide(s).

Item Term When used
Checkbox State On (☑)

Within Code: True

 Checkbox has a check in it.

For user-facing content: Use On (TagTips, Form Text, Wiki Documentation, etc.).

For code comments: You may use True, as you will be working with the boolean value directly.

NOTE: This differs from the Action performed on the Checkbox.
Off (☐)

Within Code: False

 Checkbox is cleared.

For user-facing content: Use Off (TagTips, Form Text, Wiki Documentation, etc.).

For code comments: You may use False, as you will be working with the boolean value directly.

NOTE: This differs from the Action performed on the Checkbox.
Null In some cases, checkboxes may allow a TripleState of Null; this may also be referred to as Indeterminate. See also Tri-State Null.

Example: In permission lists, if a parent permission includes children, and some of the children are set to allow, and some are off/cleared, the parent may appear in an indeterminate state.

All cases use: Null.

Appears as a square or gray interior inside the checkbox instead of a checkmark or cleared state.
UI Action Select Chose the (Option name), set (Option name) checkbox state to True.

Example: Select Use Fast Save to enable a significant performance boost.
Clear Clear (Option name) checkbox (set state to False), remove text.

Example: Clear Use Fast Save to export all elements in your file every time.
Keyboard Keystrokes <kbd> Enclose keystrokes with the <kbd> tag. To group simultaneous keystrokes, use the + charachter.

Example:

Press <kbd>[Shift]+[Q]</kbd> to do a fancy thing.

will render like this:

Press [Shift]+[Q] to do a fancy thing.
[] Use of Square Brackets ([ ]) is desirable, especially within code comments as the <kbd> tag is not rendered in the VBA IDE, and to disambiguate between combined keystrokes and the [+] key.

Example in Code: ' To break the execution of this function, Press [Ctrl]+[Break] or [Esc]

Example Wiki: To close Access immediately, press [Alt]+[F4]
Text entry in fields Enclose text entered by users with ` charachter (code formatting).

Example: Type Potato into the Desired Food box.
Referencing Field Bold To refer to a field, use Bold (Markdown= **[stuff]**)
Action Generally, the action performed does not need to be highlighted. Instead, highlight the Field or the Menu Item.

Example: Goto the Options > Export tab. Select desired Sanitize Level.

Names

Names are the most complex part of code. Chosing a name can help or hinder a future programmer's troubleshooting or adding functions. This can be future you, as well. This AddIn isn't perfect, but we're trying to be better than we were. You won't find perfect adherance to these names, but we're working to make it so.

These may change as we improve, or not. Sometimes, it's better to keep the code the way it is: change simply for the sake of change is worse than leaving something broken especially when it works as-is. There are definitely exceptions to the guidance below; new code should attempt to meet these rules, if possible.

Module / Class Naming

Naming a Module or Class should have mod or cls prefix. Because the VBA IDE doesn't export differently (and this AddIn follows suit) for classes or modules, sometimes the easiest way to tell if it's a class / module without opening the file is the name.

modConstants is an example of a Module name.

clsLog is an example of a Class name.

Function / Subroutine Names

Use PascalCase for Function and Subroutine names.

A subroutine "does" something. As a result, the name should generally be a Verb describing that action. Log.Clear is an example of the clsLog.Clear subroutine.

If the function is obtaining Something, generally prepending Get to the beginning of the something is a good idea. GetSomething would do that. If Something is a value, you can reset it with ResetSomething. LoadOptions is an example in modObjects.

There are some instances where a function is used like a property, like Log. In this case, name it like a Property. Another example is T; these are treated likethis because they are a wrapper to simplify use of the relevant classes/functions.

Properties

Properties are a variable/value/object. Name them with what they are.

Options are kept in a modObjects property Options.

Scope of Definition

Declare as low in scope as possible.

If a constant is only relevant in a particular Module or Class, declare it there. This avoids incorrect use and increases code portability. Because this is an open source project, many of these modules and classes could be used or leveraged by others. This also facilitates variable reuse such as ModuleName, which is used by several modules and classes. Keeping the scope minimized ensures each instance is properly called.

Constants

Declare Global Constants and Variables in modConstants.

Constants should be ALL_CAPS. Example: PROJECT_NAME in modConstants.

Exception: if the Constant also shares use with a Function or Property, use PascalCase to name the value. ModuleName is often a constant, but it is also technically overloaded with ModuleName as a wrapper for TypeName to allow classes to not require this constant be defined. FunctionName is similarly used.

Variables

Do not use global-scope variables. Variables should be defined in a class or property.

Module / Class Level Variables

Previously, module level defined values were defined like m_SomeVariable as a prefix.

Define variables in modules with this. Doing so opens up using IntelliType and also allows you to clear all scope level variables at once by setting this to an empty this. This is similar to using the Me keyword, but doesn't require this to be in a class instance to be useful. It is often also helpful to differentiate between Me and this.

Example using this 

Private Type udtThis
    blnSomeBit As Boolean
    SomeObject As Object
    SomeImportantObject As clsSpecial
    SomeInternalUse As clsSomethingOrOther
End Type
Private this as udtThis

Public Function IsReady() As Boolean
    IsReady = this.blnSomeBit
End Function

Public Sub Reset()

    Dim EmptyThis As udtThis

    ' To be doubly sure memory is cleared for some objects, may be worthwhile to specifically clear them out.
    Set this.SomeImportantObject = Nothing

    ' All other values will be erased/reset when you do this:
    LSet this = EmptyThis

End Sub

Function / Subroutine Variables

Define Function level variables with Hungarian Notation. Yes, yes, we know it's not "cool", but like we said above, sometimes, keeping consistency and not needing to rewrite all the code just to change the names is the right choice; this is one of those times.

Example: Dim lngIndexIDNumber As Long

Error Handling

Hoooooo boy. There's lots of ways to do Error Handling.

This code uses a few, and over the years has changed as we learn new tools and tricks.

To start, Error Handling is managed in modErrorHandling.

Error Handling for New Code

Call LogUnhandledErrors FunctionName before On Error Resume Next, where FunctionName is the name of the function + module name or is a defined Subroutine scoped Constant or Variable FunctionName.

LogUnhandledErrors

Defined in modErrorHandling.

LogUnhandledErrors(Optional ByRef CallingFunction As String = vbNullString) can be called with or without CallingFunction.

We suggest including it to speed debugging and give a hint to where code may have stopped.

Error Handling in a Class Example

Because we can use ModuleName as a wrapper for TypeName in classes, fewer items need to be defined. Downside is that you can't define FunctionName as a constant in this case.

Public Function MyFunctionName(ByRef doc As Object) As OutputThing

    Dim FunctionName As String
    FunctionName = ModuleName(Me) & ".MyFunctionName"

    LogUnhandledErrors FunctionName
    On Error Resume Next

    ' Middle of a loop or at a common issue spot:
    CatchAny eelError, "Couldn't find marbles in document: " & doc.Name, FunctionName

    ' Code doing "stuff"

   ' Way at the end (or in the middle of a routine you are looking for errors)
    CatchAny eelError, "Error getting hidden attribute for " & doc.Name, FunctionName

End Function

Error Handling in a Module Example

Private Const ModuleName As String = "modSomeName"
    ' ModuleName is typically defined in modules with the file name because we can't 
    ' use the ModuleName(Me) function to get the code instance name in a module. Maybe "ModuleName(Me) 
    ' should be renamed to "ClassName(Me)" Instead.


Public Function MyFunctionName(ByRef doc As Object) As OutputThing

    Const FunctionName As String = ModuleName & ".MyFunctionName"

    LogUnhandledErrors FunctionName
    On Error Resume Next

    ' Middle of a routine:
    CatchAny eelError, "Couldn't find marbles in document: " & doc.Name, FunctionName

    ' Code doing "stuff"

   ' Way at the end (or in the middle of a routine you are looking for errors)
    CatchAny eelError, "Error getting hidden attribute for " & doc.Name, FunctionName

End Function


Public Function SomeFastFunction () As Boolean
    ' You don't need to define FunctionName if you don't use it much. You still should, but you don't have to.

    LogUnhandledErrors "SomeFastFunction"
    On Error Resume Next

    CatchAny eelError, "Error when running this.", "SomeFastFunction"

End Function
⚠️ **GitHub.com Fallback** ⚠️