Development Standards - AronGahagan/cpt-dev GitHub Wiki

Contents

  1. Human Readable Code
  2. Naming Conventions
    1. Variables
    2. SubProcedures
    3. vbComponents
  3. Structure
  4. Version Control
  5. Releases
  6. Branching
  7. Upgrades

Human Readable Code

Code should be well commented, such that another person with reasonable VBA coding experience can step in and revise the code if necessary. To that end we should also attempt to employ some common naming conventions and an organized structure.

[ top ]

Naming Conventions

Variables

  • Individual contributors are free to name their objects and variables according to their preferred conventions, though extra points will be awarded to those who follow some kind of common naming convention. Some suggestions are below:

    Data Type Prefix Example
    Array arr- (a-) arrFields (aFields)
    Boolean bln- blnExists
    Constant CAPS BLN_TRAP_ERRORS
    Dates dt- dtStatus
    Double dbl- dblRemainingWork
    Integer int- intFile
    Long lng- lngTask, lngTasks
    Object obj- (o-) oTask, oWorkbook
    Single sng- sngCount
    String str- strFileName, strProjectName
    Variant var- (v-) vField
    Item Convention
    Applications oExcel, oPowerPoint, oMSPROJ
    MS Project Objects oProject, oTask, oResource, oAssignment
    MS Excel Objects oWorkbook, oWorksheet, oRange, oCell, oListObject, oPivotTable

SubProcedures

  • All cpt-related SubProcedures and Functions shall be prefixed with cpt to distinguish ours from theirs.

    examples: cptSetup(); cptRegex(strText As String, strPattern As String)

VbComponents

  • vbComponents (UserForms, CodeModules, and Classes) shall also be prefixed with cpt, shall named for their related feature, and shall be suffixed with the file extension for its type.

    examples: cptCriticalPath_bas; cptEvetns_cls; cptCriticalPath_frm

[ top ]

Structure

  • Each VBA Code Module shall be stored in the repository in a directories named for its parent ribbon group. E.g., the Critical Path feature lives in the Trace group on the menu:

wiki-critical-path.png

  • So its file path would be [git repo][ribbonGroup]\cpt[Feature]_[bas|cls|frm].[bas|cls|frm]:

    [git repo]\Trace\cptCriticalPath_bas.bas
[git repo]\Trace\cptCriticalPath_frm.frm
[git repo]\Trace\cptCriticalPath_frm.frx

[ top ]

Version Control

  • All modules of a feature shall have the same version. E.g., the if cptResourceDemand_bas.bas gets an upgrade then its associated cptResourceDemand_frm.frm should receive a version bump as well.
  • We will follow the Semantic Versioning strategy: [0-9].[0-9].[0-9] = [major].[minor].[patch]

[ top ]

Releases

  • A Major release in spring, minor release in Autumn, hotfixes in between.
  • Release goes to GitHub (with binary attached), then through SharePoint Portal with notifications so people can subscribe.

[ top ]

Branching

<-- this section wip -->

After a release (at an offsite) the master branch is locked down for feature improvements; only hotfix branches are merged into master; the develop branch becomes the next release candidate; new features are developed in their own branch and merged into the next release branch upon review and approval by stakeholders.

  1. Branch master shall only be modified by pulling from branch develop. The master and develop branches are the only two long-running branches.
  2. Create topic (a.k.a. hotfix) branches from develop, and when complete merge the topic branch into both develop and master.
  3. Create feature branches from develop.
  4. Branch develop may be modified directly, though it is preferable to open a new feature/hotfix branch then merge that branch into develop when complete. Once fully tested merge develop into master for 6 month release.
  5. A release branch shall be created from the develop branch for 6-month releases. Merge hotfixes into develop and release.
  6. General coding session steps:

    1. Open MS Project

    2. Open gitVBA dialog

    3. Create a new (feature|hotfix) branch; prefix with f- or h- accordingly. _Alternatively, name the hotfix for the associated Issue; e.g. git checkout -b develop issue30.

    4. Open coding session: run Checkout to import modules from develop (or feature, or hotfix) branch into your Global.MPT

    5. Develop and test, run Save and Add on all project-related modules from time to time.

    6. If you turned off error trapping (in the CodeModule's Private Const BLN_TRAP_ERRORS variable) be sure to reset to to TRUE.

    7. If you early-bound any object variables for design time, be sure to switch them back to late-bound before staging them for the next commit (but please keep the reference commented). e.g.,

      Dim vbComponent As vbComponent          '<-- at design time
Dim vbComponent As Object 'vbCompnent   '<-- before commit

    8. When complete, rev the codemodule(s), then run a final Save and Add to ensure all modifications are staged.

    9. Manually update CurrentVersions.xml and stage it.

    10. Commit your changes to the working directory, adding a descriptive commit comment. example:

      git commit -m 'issue #30 resolved - now it does the dishes too'

    11. Close Session to remove project-related modules from Global.MPT.

    12. Submit a pull request to review before merging 'up' the chain.

[ top ]

Upgrades

  1. 'Upgrade' is any upgrade, update, hotfix, etc. All basically involve a remove/replace of a CodeModule (whether *.bas, *.frm, or *.cls). The rare exception would be ThisProject_cls.cls which must be handled very carefully.
  2. Upgrades can be applied to everything except cptUpgrades_frm.frm. Update cptUpgrades_frm.frm using cptPatch_bas.bas or by prompting the user to re-run cptSteup().

[ top ]