| Tagging Objects and Code | KEVIN RESCHENBERG
01-10-2005 |
Last week I wrote about the necessity of a good issue tracking system. This
week we will link it to our custom objects and code.
One thing that the issue tracking system must give us is a unique,
unchanging issue ID (usually a number). That's the token that allows us
to track back from an object to the main documentation contained in the
issue.
For PeopleSoft objects (fields, pages, etc.): Put the issue ID into the
object's Properties box, along with a short description of the change. For
example: "XYZ Co. issue 123: Moved Widget Name field to left margin."
For PeopleSoft projects: The project is a list of the objects you have
changed. Put the issue ID into the Project Properties box, but I'd also suggest
naming your project using the issue ID. Use your unique custom
identifier (see Identifying Custom Objects)
and the issue ID as the name of your project. For example, if the unique
identifier you use is "X" and the issue ID is 123, you could name the project
"X_123". Many people will object to this suggestion—why not give it a more
descriptive name? I'll discuss that below.
For SQR and COBOL code: Add a short description at the top of the program
and include the issue ID. If this is a completely new program, that's the only
place you need to show the issue ID. However, if the issue led to changes to
an existing program, you should tag every changed line:
let #a = 1 ! 123
! let #b = 2 ! 123
let #b = 20 ! 123
In this example, the first line (#a = 1) was added. The second line (#b = 2)
existed in the previous version but has now been replaced by the third line
(#b = 20). This illustrates the following two simple rules:
- Never actually change or delete a line. Comment it out instead and add
the replacement (if any) below it. Tag both lines with the issue ID.
- When you add a line, tag it.
Following these rules will allow you to roll back at least the latest change
to a program, and usually several changes. The issue ID tags also allow
you to refer back to the issue documentation itself, which will almost always be more
useful than any cryptic comment in the program.
I'll repeat this advice in the future. It has really saved me from big problems
in the past.
So, why would I want to name a project "X_123" instead of "X_WIDGET_PAGE"?
First, we have very little space to work with. "Widget page" doesn't tell us
much about what was created or changed. "X_123" is far more descriptive in that
it refers back to the issue, with all of its documentation and history.
The main reason, though, is that including the issue ID helps us track in
the other direction, from the issue to the objects and code. If we are reading
an issue description and want to find the objects, we simply look for the
project with that standard name: X_123. The project then points us to the
other objects. (Note that SQRs, COBOL programs, scripts, etc. are not stored
in a project. You should either include their names in the Project Properties
box, or include a "file reference" object in the project. A file reference
is simply a pointer to an external file. It doesn't cause the file to be
migrated by Application Designer, but it's a good reminder and documentation.
File references are available at releases 8.x.)
|
