IT:AD:Code Comments:Examples:Novels

(UP)

Summary

Writing code is an expensive process. Add in the reality of staff rotation, and the argument for documentation right where the developer is working (rather than an external system) is validated.

But there's a point where it goes to far.


/*
 This is the widget method which will process the list of
 widgets from the widget controller and service in order to
 handle pre-processing (where the widget information is
 compared against the average widget history), actual
 processing (where the quarterly, monthly and week attributes
 are updated) and all of the post-processing (which include the
 analytical metrics and audit table updates) aspects. It is
 important to remember the widget rules around leap year where
 the cost to transfer rate is 75% adjusted to the annual rate in
 order to account for the extra day. When this happens, the
 process will throw the LeapYearException which will need to be
 validated by the application support staff. Failure to do so will
 end up causing issues with the ME-4110 report.
*/

A rule of thumb is that any section of code that requires that much information should probably be broken down into smaller methods.

If nothing else, the information in the comments should reside outside the actual code, where a documentation service can pick it up and publish it.