Re: Documenting code changes

On 9/27/2013 3:24 PM, Stone, Joel wrote:

I don't think that there is one simple solution for all your changes.

For tiny changes, commenting out the old stuff and adding a new line is great! For example, if replacing a hard-coded network path with a variable path:

The "004" is NOT the ticket #, rather the source version # for this particular CL. For example, the following is the 4th change to this pgm since pgm creation. At the top of source is a comment relating the "004" to the ticket #.

/*@004D CHGRDIR RMTDIR('CorpNetworkServer/FTP/Receive/Test') */
/*@004A*/ CHGRDIR RMTDIR(&NET_DIR)

The above is intuitive and is helpful for future pgmrs (or myself as my memory weakens) when it is looked at in 6 months.

When I was younger I used to enter obfuscated code contests. You know,
the ones where someone would post a chunk of code (often C) and the
contestants try to suss it out. Almost all of these contests involved
hideous formatting. Removing most or all white space, breaking keywords
at odd places, multiple statement fragments on a single line and the old
standby: using commented out 'code' to sadistically imitate actual code.

For a larger mod such as removing 500 lines of code and replacing with a callable reusable pgm, go ahead and delete the 500 lines and key a comment stating so much.

When people are browsing and searching thru code, it is unlikely that they will have the time to refer to archives in general. Depends on how much time is available and how bad they want to know what "was". Having small changes documented in the source can really be a time saver.

It seems to me that comments ought to enlighten the reader about the
intent of the code. I personally can't understand how obsolete code
could do that.
--buck