A kilobyte of comments

I’m not sure which fact is more hilar­i­ous (or sad): that I have a three-line func­tion with twen­ty-eight lines of com­ments, or that the func­tion exists at all.

At some point I was instruct­ed not to use pub­lic vari­ables and to cre­ate get­ters and set­ters for every­thing. Encap­su­la­tion is a good thing, but for val­ues that just need to be accessed it makes just as much sense to make the vari­able pub­lic and not waste a func­tion call to return the variable.

But what if some­one sets a val­ue they should­n’t? Well, some­times that’s a prob­lem but frankly often it isn’t. Since this is part of an object that only I or some­one I might be super­vis­ing will ever use, there is a lim­it to the effort I’m will­ing to put into idiot­proof­ing my code. Nev­er mind the lim­it to how much mon­ey my client is will­ing to spend on me idiot­proof­ing my code.

Why don’t I just remove the func­tion? I prob­a­bly have code some­where that uses it. I can live with it return­ing less infor­ma­tion than I orig­i­nal­ly intend­ed, but I don’t want to intro­duce fatal errors.

On the oth­er hand, fatal errors are good because they are real­ly obvi­ous in test­ing. But only if I actu­al­ly test every­thing that ever used this func­tion. So it stays for now and I get to fig­ure out where it’s being called some­time when I’m not in the mid­dle of try­ing 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;
}

Hope­ful­ly I get bonus irony points for the func­tion being named comments().