A kilobyte of comments

(Originally posted to Monochromatic Outlook)

I’m not sure which fact is more hilarious (or sad): that I have a three-line function with twenty-eight lines of comments, or that the function exists at all.

At some point I was instructed not to use public variables and to create getters and setters for everything. Encapsulation is a good thing, but for values that just need to be accessed it makes just as much sense to make the variable public and not waste a function call to return the variable.

But what if someone sets a value they shouldn’t? Well, sometimes that’s a problem but frankly often it isn’t. Since this is part of an object that only I or someone I might be supervising will ever use, there is a limit to the effort I’m willing to put into idiotproofing my code. Never mind the limit to how much money my client is willing to spend on me idiotproofing my code.

Why don’t I just remove the function? I probably have code somewhere that uses it. I can live with it returning less information than I originally intended, but I don’t want to introduce fatal errors.

On the other hand, fatal errors are good because they are really obvious in testing. But only if I actually test everything that ever used this function. So it stays for now and I get to figure out where it’s being called sometime when I’m not in the middle of trying to get things fixed.

/**
 * @deprecated since version 0.1.1
 * 
 * $COMMENTS is now public. Prior to 0.1.1 it contained not only the
 * comment id and metadata but also the text of each comment. This was
 * wasteful especially because of a recursive condition where a new
 * comment could contain all prior comments. Not an endless loop, but 
 * still a memory bloater.
 * 
 * Considering all the diagnostic information that could potentially
 * be in the comment table at this point, the most likely thing you
 * want to do is loop through $COMMENTS and then call getComment() on 
 * whatever you actually want. Or query the table directly.  
 * 
 * @see $COMMENTS          contains the info you actually want
 * @see getAllCommentIDs() which populates $COMMENTS
 * @see getAllComments()   if you really want all the comment data. It
 *                         costs only one query, but it's expensive on 
 *                         memory
 * @see getComment()       if you want the contents of an individual
 *                         comment
 * @return array           which looks like this:
 *       array( 
 *         int id => array(
 *                     'id'         => int,
 *                     'created'    => date,
 *                     'comment_by' => string
 *                   )
 *       );
 */
function comments( ) {
  return $this->COMMENTS;
}

Hopefully I get bonus irony points for the function being named comments().