Success in the world of software development and quality assurance is inevitably defined by the ability of programmers and testing personnel to create and maintain thousands of lines of code in a way that efficiently meets the needs of their customers. Any developer will tell you there’s almost always multiple ways to write code that will satisfy a given set of requirements. Obviously, meeting these requirements is what’s most important. No one can overlook that. The software must perform, or it is worthless. However, something that is also very important, but often overlooked, is the documentation of what is being coded/tested.
For example, let’s say a staffing software sale has just been made. The consultant has written up the spec., and the customer has signed. Now Peggy the Programmer has 2 weeks to write the code that will satisfy the 15 Microsoft Dynamics GP functionality requirements that are laid out in the agreement. In her haste, she starts thinking, “Well, I’ve got 15 things I need to make work and only so much time to make them work, so I better just start jackhammering away at the keyboard.” Incorrect, poor Peggy. Before she knows it she has hundreds or thousands of lines of code and no way to efficiently navigate her way through them.
In order to save a considerable amount of time and effort down the road, as she codes, Peggy should document the features she is adding. She can include simple notes in the code like “#Suggestion 115: Add Invoice Format ID to Temporary Placement” and “#Suggestion: 116: Add the Ability to Post Multiple PAM Batches through to the General Ledger Batches at once.”
What are the benefits to such documentation?
For one, it takes just seconds to do, so even if you never reference anything you’ve documented, there’s no real downside.
Also, it will help Peggy find the specific lines of code that need to be fixed if something should break in the future. Let’s assume Peggy is a pretty proud person. Her line of thinking is “I don’t make mistakes very often, and even if I do, I wrote the code so I know exactly where to look to fix it if something goes wrong.”
Well, what happens if the new Invoice Format ID malfunctions the day she leaves for her annual two week snorkeling, scuba diving, and surfing trip to Hawaii, and a customer needs to process payroll by Wednesday? How is her coworker, Darryl the Developer, supposed to know how to efficiently find the code that’s causing the problem? If she would have documented the 5 places in the code where she made changes, Darryl could simply search “Suggestion 115,” look at the 5 areas that pertain to this feature, find the problem, and make the fix. Instead, proud Peggy gets to spend Tuesday of her vacation surfing on her laptop trying to find the problem when she’d much rather be surfing the waves of Oahu.
Such documentation also assists quality assurance personnel during testing of products built in Microsoft Dynamics GP. “#Begin testing Suggestion 116” and “#End testing Suggestion 116” is all that is needed in the macro’s code to make the analysis of what needs to be fixed transpire as smoothly as possible. If the macro crashes somewhere in between these comments in the code, Tammy the Tester can search “Suggestion 116” in the Problem Report Database, jog her memory as to what feature the issue is related to, and relay the information to the programmer in a timely fashion. Without the documentation, Tammy will likely know the problem is related to General Ledger, but it will be difficult for her to remember that this specific part of the macro tests the feature of posting multiple PAM batches. And what happens if after Tammy retires something breaks?
[In the automated testing arena, macros aren’t simply run successfully one time, and all is well. Every macro in the macro suite for the product must run successfully, and its reports must be verified and accepted as the new standard for future testing. For quality assurance purposes, every past feature or fix that has been added gets tested after new code is introduced and before the product is released.]
Now Tammy’s heir, Tony the Tester, will have no way of knowing what caused the error message that pops up when one of the macros crashes.
So, for Tony, Tammy, Darryl, and Peggy’s sake, just take a few seconds here and there to document specifically what you’re coding and testing. It will definitely save you minutes, if not hours, days, or weeks, by the time all is said and done… and it might even end up saving you a Hawaiian headache!!