PICOL Comment

Today, programmers, let us celebrate all the varied and wonderful facets of code commenting: an art that too few of our brethren bother with, and even fewer master. Those who do stand to leave their mark on untold generations to come!

There are the comments that make us laugh out loud, as Hopsas illustrates:

//  ( ͡° ͜ʖ ͡°)
    public DocMgmtDocumentHead giveHead() {
        DocMgmtDocumentHead newHead = new DocMgmtDocumentHead();
        newHead.setDocMgmtDocumentBody(new DocMgmtDocumentBody());
        newHead.setDocMgmtDocumentType(new DocMgmtDocumentType());
        return newHead;

There are the comments that serve as time capsules, as Tyler Z. learned when he ventured into the innards of an old ActiveX component still used at his company:

// check for any streams which have not had a response in time.
// Thanks to that idiot Bill Gates and his recent purchase of the US
// Government we are not allowed to use GetURLNotify
// or PostURLNotify. Since failing silently tends to confuse the users
// who have already been confused enough by Microsoft Marketing hype 
// we need to take this approach. 
void streams::check_for_timeouts(time_t now)

And then, as Dash shows us, there are the seemingly rational comments that highlight the workings of a disturbed mind.

function total_working_days($startDate,$endDate) {
    // Calculate weekday number. Monday is 1, Sunday is 7 
         $firstWeekdayNumber = date("N", strtotime($startDate)); 
    $lastWeekdayNumber  = date("N", strtotime($endDate)); 

    // Normalize the dates if they're weekends or holidays as they count for full days (24 hours) 
    if ($firstWeekdayNumber == 6 || $firstWeekdayNumber == 7) 
        $startDate = date("Y-m-d 00:00:00", strtotime($startDate)); 
    if ($lastWeekdayNumber == 6  || $lastWeekdayNumber == 7 ) 
        $endDate   = date("Y-m-d 00:00:00", strtotime("+1 days", strtotime( $endDate ))); 

    // Compute the floating-point differences in the dates 
    $daysDifference          = (strtotime($endDate) - strtotime($startDate)) / 86400; 
    $fullWeeksDifference     = floor($daysDifference / 7); 
    $remainingDaysDifference = fmod($daysDifference, 7); 

    // Subtract the weekends; In the first case the whole interval is within a week, in the second case the interval falls in two weeks. 
    if ($firstWeekdayNumber <= $lastWeekdayNumber){ 
        if ($firstWeekdayNumber <= 6 && 6 <= $lastWeekdayNumber && $remainingDaysDifference >= 1) $remainingDaysDifference--; 
        if ($firstWeekdayNumber <= 7 && 7 <= $lastWeekdayNumber && $remainingDaysDifference >= 1) $remainingDaysDifference--; 
        if ($firstWeekdayNumber <= 6  && $remainingDaysDifference >= 1) $remainingDaysDifference--; 
        // In the case when the interval falls in two weeks, there will be a Sunday for sure 

    // Compute the working days based on full weeks + 
    $workingDays = $fullWeeksDifference * 5; 
    if ($remainingDaysDifference > 0 ) 
        $workingDays += $remainingDaysDifference; 

    // Subtract the holidays 
    // End of calculation, return the result now 
         //echo $workingDays; 
 return $workingDays + 1; 
 //echo $ass_b2;die;

[Advertisement] Manage IT infrastructure as code across all environments with Puppet. Puppet Enterprise now offers more control and insight, with role-based access control, activity logging and all-new Puppet Apps. Start your free trial today!