Commenting Interactive Code
March 7, 2012 Ted Holt
|
The tips I regularly feature in this august publication deal with some aspect of source code syntax. Today I turn my attention to another part of the programming process. I want to talk about a work habit that you might find useful. I would say that everyone who writes any type of source code at all knows the importance of comments, but that would be incorrect. I have followed (and written) too much code that was inadequately commented. Effective comments in source code serve as a great boon to the humans who must read or modify source code. As Ashley Phix reminded all of you Aries last April, comments that tell why something is being done are more useful than those that tell what is being done. Today I want to point out that comments may also be useful in interactive settings. For example, suppose you are developing an SQL query. After several attempts, you may begin to confuse the various queries you’ve run, not sure which ones were successes and which ones were duds. You can help yourself by recording your thought process in comments as you work through your problem. Here’s an example from a green-screen SQL session. (I’ve replaced the bulk of the select statements with ellipses to make the example more succinct.) -- 3-7-2012, project 13774 SQL statement empty or blank. -- method 1 -- use a common table expression SQL statement empty or blank. select . . . SELECT statement run complete. select . . . SELECT statement run complete. select . . . SELECT statement run complete. -- the last one works fine SQL statement empty or blank. -- method 2 - use a subquery SQL statement empty or blank. select . . . SELECT statement run complete. -- no good - can't select all the required fields If you have to leave a project and return to it later, the comments you make may decrease the time it takes you to get back up to speed. You can also write CL comments on a CL command line. The system will ignore them, but they’ll show up in the job log. I know of a shop that puts comments in CL commands in the Robot/SCHEDULE job scheduler. These comments include the project number, which gives the shop an audit trail in case questions arise, and document changes to the job scheduler for the benefit of IT audits. Unfortunately, the Change Job Schedule Entry (CHGJOBSCDE) command doesn’t allow comments in the CMD parameter. The Florida Orange Juice Growers Association claims that orange juice is not just for breakfast anymore. Maybe I should say that comments aren’t just for programs and scripts anymore. RELATED STORY
|
