Eulogy takes advantage of two features within the G programming language and the LabVIEW development environment: (i) Diagram Disable Structures and (ii) Bookmarks. Diagram Disable Structures have been available in the G programming language since LabVIEW 8, and are akin to comment blocks in text-based programming languages. Bookmarks have been available since LabVIEW 2013. In essence, Eulogy is a framework and/or set of conventions for using these two features to refactor legacy code.
The Eulogy framework is based on the concept of a "grave" and the desire to bury, or remove, dead, legacy code from a codebase. A grave is simply a Diagram Disable Structure with a specific format for its label and two frames with formatted subdiagram labels and names. The Diagram Disable Structure label of a grave includes the
#RIP bookmark tag, an ISO 8601 timestamp string of when the grave was created, and a developer's name surrounded by parentheses. Within Eulogy, the label for a Diagram Disable Structure that matches this format is known as a "tombstone", while the timestamp is known as the Time of Death (ToD) and the developer's name is known as the "grave digger".
A grave contains disabled frame that includes the legacy code to eventually be removed, and an enabled framed that includes the refactored code to remain after the legacy code is removed. The legacy code frame is known as the "Corpse" and the refactored code frame is known as the "Spirit". The names of each frame are used for the subdiagram labels of the Diagram Disable Structure. When a grave is first created, or "dug", it is also convention to create a copy of the Corpse frame and use it to create the Spirit frame. The following image shows the Corpse and Spirit frames of the same example grave:
Graves make up the most basic concept and convention of Eulogy, but once a grave exists the inherent features of the Diagram Disable Structure can be used to manage the refactoring process. There might be times when the refactored code (Spirit frame) is still a broken work-in-progress but the whole VI must be run. In this case, the refactored code should be disabled (Spirit frame) and the legacy code should be enabled (Corpse frame). In other words, the code should be reverted to the legacy state. This would be the equivalent of commenting out the refactored code and un-commenting the legacy code in a text-based programming language.
In the G programming language, when a Corpse frame is enabled using the shortcut menu of the Diagram Disable Structure, there exists "dead" code that has come back to life, or been reanimated. This is known as a "zombie" in Eulogy. The convention is to replace the "Corpse" subdiagram label with a
#Zombie bookmark tag followed by an ISO 8601 timestamp string of when the zombie was reanimated then the developer's name that created the zombie surrounded by parentheses. This is a similar format to the tombstone label for the grave. The timestamp for the zombie is known as the "Rebirthday" and the developer is known as the "Necromancer". The following image shows an example Zombie at a grave:
Once the refactoring in the Spirit frame is completed and longer causes a broken VI, the zombie can be converted back to a corpse. The subdiagram label for the Corpse frame (legacy code), is not changed back to the "Corpse" label. Instead, the zombie text for the Corpse frame's subdiagram label is left unmodified to keep a log of the last time the legacy code had to be used. The enabled/disabled state of the Corpse frame is used to indicate if the zombie is alive or not. The process of enabling the Spirit frame and disabling the Zombin frame is known as "smiting".
After the refactored code has been verified to not introduce new bugs or side-effects, it is time to remove the legacy code for good and only keep the refactored code. The grave is removed from a block diagram by ensuring the Spirit frame is visible and the Remove Diagram Disable Structure menu item is executed from the shortcut menu for the Diagram Disable Structure. This will remove the grave and leave behind only the refactored code (Spirit frame). In Eulogy, this is known as "burying a corpse", or simply "bury".1 The following image shows an example of a grave where Zombie has been smited. Notice the Spirit frame has been enabled and the original Corpse frame has been disabled but the Zombie-related subdiagram label is unmodified.
Since a grave's tombstone and a zombie contain bookmarks, the default LabVIEW Bookmark Manager, View>>Bookmark Manager, can be used to find all graves and zombies in a project or codebase. A developer can jump to any grave or zombie in any VI that is in a project or memory. This makes navigating and managing a series of refactoring tasks easier, and it only uses features provided by the LabVIEW development environment.
It can be tedious to manually create graves (dig), enable legacy code (reanimate), disable legacy code (smite), and remove graves (bury) using only the built-in menus and actions for Diagram Disable Structures. Creating a grave is especially cumbersome because of the multiple steps involved. For example, there is no built-in, quick way of wrapping a selection of several block diagram objects/nodes in a Diagram Disable Structure. Also, the LabVIEW Bookmark Manager functionality is a little too generic and limited because it shows all bookmarks. Graves cannot be directly manipulated from within the default Bookmark Manager. Thus, Eulogy consists of five (5) components that make up the add-on and toolkit for working with graves easier and more efficient:
- Custom Bookmark Manager (Graveyard)
- Quick Drop Keyboard Shortcuts
- Shortcut Menu Plugin
- Tools Menu
- Toolkit API
- It is best practice to save a new version of the code within a version control system when bury occurs.↩