Hidden Gems: Part 1
With every major release of the looksoftware product suite a bunch of new features are made available. However we often find that some of those features are misunderstood, underutilized and occasionally overlooked to the detriment to both you, the developer, and the solutions you create.
As part of an ongoing series we plan to revisit the product features that historically have fallen into the "Hidden Gem" category.
The first of these underutilized features is Change History Management within the looksoftware IDE which we'll discuss in further detail.
Why should we document changes?
When creating software there are many factors that help distinguish good code versus bad code. Some of those factors include whether the code actually works (obviously), how simple and effective the code is, and how easy it is for someone other than the original author to maintain the code.
In a lot of cases well written code can be relatively straightforward for a competent developer to look at and follow, however this will often come down to the practices and standards used by the original author.
One very common method of making code easier to understand is the use of in-code comments to explain the purpose of the code and what each of the sections relate to. looksoftwares IDE supports its own macro language as well as Jscript and VBscript, all of which fully support commenting.
Comments should be added in sufficient detail to allow you to return to the macro/script in several months, and at a glance, know what you did. Such detail will also to allow someone unfamiliar with the reason behind the macro/script to know its purpose. The comments dont need to be for the layman so its safe to assume proficiency in the language for the reader.
Comments within scripts and macros are all fine and good but how do you add comments about work you have done, in creating either a host or custom (added) form? Fortunately the answer is simple in that you just enable change history management within the IDE.
What is Change History Management?
Change history management allows the developer using the looksoftware development tools to add comments for host or added forms they have created and/or modified. This allows the developer to explain the reason for the override as well as allow them to explain each of the individual changes made. For example, a sample comment could be "Customizations were made based on feedback from the accounts team. A frame was added around the customer address fields".
Enabling Change History Management
Change history management is enabled globally and applies to a specific solution only. To enable change history management you can turn on the Enable change history management option under Rules | General (refer to Figure 1). This setting is stored within the shared repository (SID).
Figure 1 : Enabling change history management
What can be stored?
Once enabled, any change made to an existing form will prompt you to add a comment (refer to Figure 2). Make sure the comments are as descriptive as required in order for you or another developer to be able to review the history, and determine why a specific change was made.
The author field will default to the user defined within Windows however it can be overwritten if using a shared computer.
Figure 2 : Adding comments for each change made
How do you review changes?
So now that youve enabled change history reviewing what changes have been made is very simple. When you open a host or added form, there are 3 tabs at the bottom of the form that allow you to switch between Design, Identify and Change History (2 tabs with added forms). To view the change history simply select the tab and youll be presented with a list of the changes made, including time/date, author and the description (refer to Figure 3).
Figure 3 : Reviewing changes
Although not technically a component of change history management, the properties of an override also allows you to view valuable information such as the original author, last author as well as add comments and revision information. To view and edit this information simply bring up the forms list and expand the property sheet (refer to figure 4). This information is available even if you havent enabled change history management.
Figure 4 : Form properties
Change history management is a useful tool to allow developers to document and keep track of changes they make to forms within their solution.
Any feedback on this functionality is welcome and can be sent direct to firstname.lastname@example.org
Support Manager, looksoftware