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.