Tech Tip: A New Place for Your Comments?
I just gave a two-day, "Best of Oracle PL/SQL" training to a team of developers in Winona, MN, home of the Sugar Loaf Bluff, which I climbed after the first day of training.One of the development managers, Jason McClellen of Fastenal, offered the following suggestion when I talked about the importance of application tracing or instrumentation:
Comments are usually added to code as "static" text, visible only when you open up and look at your source code. Instead of hiding away your comments, include them in the calls to your tracing mechanism. That way, whenever tracing is enabled, you not only see values of data being manipulated by the program, you also read information that informs your understanding of that data.
I think this is a fantastic idea, and I plan to start doing this in my own code. In Quest Code Tester for Oracle, I use a variation on the Quest Error Manager to do my tracing, so a trace call (preceded by a comment) might look like this:
/*
Simple datatypes require an initial value. This "value"
includes the assignment operator to simplify template construction.
*/
IF qu_runtime.trace_enabled
THEN
qu_runtime.
trace (
'set_placeholders typename'
, outcome_in.result.attribute.datatype_declare
);
END IF;
In the future (in fact, right now - I will "refactor" this code), my tracing will look like this:
IF qu_runtime.trace_enabled
THEN
qu_runtime.
trace (
'set_placeholders'
, 'Simple datatypes require an initial value. This "value" '||
'includes the assignment operator to simplify template construction.'
);
qu_runtime.
trace (
'set_placeholders typename'
, outcome_in.result.attribute.datatype_declare
);
END IF;
I then asked readers to tell me what they thought. Several people wrote in and I will post this in a reply. Feel encouraged to add your own thoughts.
2 comments:
Here are comments I received:
From Keith:
One bad point maybe: in TOAD, the comment won’t be green anymore – it just looks like any other string in more code.
From Mathieu:
In your newsletter you bring up the idea to move comments to a trace procedure instead of “static” text.
I can see why you want this.
But on the other hand “static” text between /* */ or -- has the advantage that it gets a different color in proper developer tool like TOAD, PLSQL developer, UltraEdit, etc. This way there is a better distinction between code and documentation. It makes reading the code much easier.
With an extra trace line for your comment you won’t have this.
I personally think that the trace text itself should be self explaining enough.
From Marcus:
our code gives you *very* much information if you switch debug on. If we include the comments it will become unreadable. Maybe it's helpful for someone new to the code but in my trace I would only accept it if I have another switch "verbose on/off".
And from Thomas:
I’m using tracing since 2002 where I got a large monolithic PL/SQL Package to maintain. After adding static comments and simple tracing I realized the advantage of explaining the workflow in the trace.
This is useful when testing with real data (I don’t know what’s coming in). It is easier to check if the packages are doing what I expect depending on the type of data. Often I don’t need to look at the code anymore.
Over the years the package is now split in smaller packages and there are stable packages I didn’t look at for month.
Despite this I use static comments as well for lengthy explanations, design decisions or ticket ids of our tracking system.
Post a Comment