Какой лучший комментарий в исходном коде вы когда-либо встречали? [закрыто]

Какой лучший комментарий в исходном коде вы когда-либо встречали?

Я особенно виноват в этом, встраивая неконструктивные комментарии, поэзию кода и небольшие шутки в большинство моих проектов (хотя у меня обычно есть достаточно смысла, чтобы удалить что-либо прямо оскорбительное перед выпуском кода). Вот один из тех, которые мне особенно нравятся, расположенные далеко, далеко внизу плохо спроектированный «Объект Бога»:

/**
* For the brave souls who get this far: You are the chosen ones,
* the valiant knights of programming who toil away, without rest,
* fixing our most awful code. To you, true saviors, kings of men,
* I say this: never gonna give you up, never gonna let you down,
* never gonna run around and desert you. Never gonna make you cry,
* never gonna say goodbye. Never gonna tell a lie and hurt you.
*/

МНЕ ЖАЛЬ!!!! Я просто не мог с собой поделать .....!

И еще один, который, как я признаю, на самом деле я не выпустил в дикую природу, хотя у меня очень искушение сделать это в одном из моих менее интуитивных классов:

// 
// Dear maintainer:
// 
// Once you are done trying to 'optimize' this routine,
// and have realized what a terrible mistake that was,
// please increment the following counter as a warning
// to the next guy:
// 
// total_hours_wasted_here = 42
// 

Exception up = new Exception("Something is really wrong.");
throw up;  //ha ha

//When I wrote this, only God and I understood what I was doing
//Now, God only knows

stop(); // Hammertime!

Это, кажется, мешает дебилам испортить мой код ...

// Autogenerated, do not edit. All changes will be undone.

// sometimes I believe compiler ignores all my comments

// I dedicate all this code, all my work, to my wife, Darlene, who will 
// have to support me and our three children and the dog once it gets 
// released into the public.

//Code sanitized to protect the foolish.
using System;
using System.Collections.Generic;
using System.Text;
using System.Reflection;
using System.Web.UI;

namespace Mobile.Web.Control
{
    /// <summary>
    /// Class used to work around Richard being a fucking idiot
    /// </summary>
    /// <remarks>
    /// The point of this is to work around his poor design so that paging will 
    /// work on a mobile control. The main problem is the BindCompany() method, 
    /// which he hoped would be able to do everything. I hope he dies.
    /// </remarks>
    public abstract class RichardIsAFuckingIdiotControl : MobileBaseControl, ICompanyProfileControl
    {
        protected abstract Pager Pager { get; }

        public void BindCompany(int companyId) { }

        public RichardIsAFuckingIdiotControl()
        {
            MakeSureNobodyAccidentallyGetsBittenByRichardsStupidity();
        }

        private void MakeSureNobodyAccidentallyGetsBittenByRichardsStupidity()
        {
            // Make sure nobody is actually using that fucking bindcompany method
            MethodInfo m = this.GetType().GetMethod("BindCompany", BindingFlags.DeclaredOnly | 
                BindingFlags.Instance | BindingFlags.Public | BindingFlags.NonPublic);
            if (m != null)
            {
                throw new RichardIsAFuckingIdiotException("No!! Don't use the fucking BindCompany method!!!");
            }
            // P.S. this method is a joke ... the rest of the class is fucking serious
        }

        /// <summary>
        /// This returns true if this control is supposed to be doing anything
        /// at all for this request. Richard thought it was a good idea to load
        /// the entire website during every request and have things turn themselves
        /// off. He also thought bandanas and aviator sunglasses were "fuckin' 
        /// gnarly, dude."
        /// </summary>
        protected bool IsThisTheRightPageImNotSureBecauseRichardIsDumb()
        {
            return Request.QueryString["Section"] == this.MenuItemKey;
        }

        protected override void OnLoad(EventArgs e)
        {
            if (IsThisTheRightPageImNotSureBecauseRichardIsDumb())
            {
                Page.LoadComplete += new EventHandler(Page_LoadComplete);
                Pager.RowCount = GetRowCountBecauseRichardIsDumb();
            }
            base.OnLoad(e);
        }

        protected abstract int GetRowCountBecauseRichardIsDumb();
        protected abstract void BindDataBecauseRichardIsDumb();

        void Page_LoadComplete(object sender, EventArgs e)
        {
            BindDataBecauseRichardIsDumb();
        }

        // the rest of his reduh-ndant interface members
        public abstract string MenuItemName { get; set; }
        public abstract string MenuItemKey { get; set; }
        public abstract bool IsCapable(CapabilityCheck checker, int companyId);
        public abstract bool ShowInMenu { get; }
        public virtual Control CreateHeaderControl()
        {
            return null;
        }
    }
}

Обновление: автор оригинального кода раскрыл себя, поэтому я должен отдать должное, где он должен. Дэн Маккинли покинул компанию, с которой я был, вскоре после того, как я начал, и он больше говорит о коде, объясняя некоторые предпосылки и еще несколько «WTF», которые написал «Ричард».

// somedev1 -  6/7/02 Adding temporary tracking of Login screen
// somedev2 -  5/22/07 Temporary my ass

// drunk, fix later

Жаль, что я шутил. И зная разработчика, который написал код, я думаю, что он имел в виду буквально.

// Magic. Do not touch.

#define TRUE FALSE //Happy debugging suckers

// I'm sorry.

return 1; # returns 1

/* This is O(scary), but seems quick enough in practice. */ 

сопровождаемый четырьмя вложенными циклами

// Replaces with spaces the braces in cases where braces in places cause stasis 
   $str = str_replace(array("\{","\}")," ",$str);

Это говорит о нашей профессии, и когда нас спрашивают о «лучшем комментарии», мы все отвечаем худшими комментариями, которые мы можем найти ...

long john; // silver

Catch (Exception e) {
 //who cares?
} 

/**
 * Always returns true.
 */
public boolean isAvailable() {
    return false;
}

Никогда не полагайтесь на комментарий ...

/*
 * You may think you know what the following code does.
 * But you dont. Trust me.
 * Fiddle with it, and youll spend many a sleepless
 * night cursing the moment you thought youd be clever
 * enough to "optimize" the code below.
 * Now close this file and go play with something else.
 */ 

try {

} finally { // should never happen 

}

От: https://github.com/zepouet/Xee-xCode-4.5/blob/master/XeePhotoshopLoader.m#L108

// At this point, I'd like to take a moment to speak to you about the Adobe PSD
// format. PSD is not a good format. PSD is not even a bad format. Calling it
// such would be an insult to other bad formats, such as PCX or JPEG. No, PSD
// is an abysmal format. Having worked on this code for several weeks now, my
// hate for PSD has grown to a raging fire that burns with the fierce passion
// of a million suns.
//
// If there are two different ways of doing something, PSD will do both, in
// different places. It will then make up three more ways no sane human would
// think of, and do those too. PSD makes inconsistency an art form. Why, for
// instance, did it suddenly decide that *these* particular chunks should be
// aligned to four bytes, and that this alignement should *not* be included in
// the size? Other chunks in other places are either unaligned, or aligned with
// the alignment included in the size. Here, though, it is not included. Either
// one of these three behaviours would be fine. A sane format would pick one.
// PSD, of course, uses all three, and more.
//
// Trying to get data out of a PSD file is like trying to find something in the
// attic of your eccentric old uncle who died in a freak freshwater shark
// attack on his 58th birthday. That last detail may not be important for the
// purposes of the simile, but at this point I am spending a lot of time
// imagining amusing fates for the people responsible for this Rube Goldberg of
// a file format.
//
// Earlier, I tried to get a hold of the latest specs for the PSD file format.
// To do this, I had to apply to them for permission to apply to them to have
// them consider sending me this sacred tome. This would have involved faxing
// them a copy of some document or other, probably signed in blood. I can only
// imagine that they make this process so difficult because they are intensely
// ashamed of having created this abomination. I was naturally not gullible
// enough to go through with this procedure, but if I had done so, I would have
// printed out every single page of the spec, and set them all on fire. Were it
// within my power, I would gather every single copy of those specs, and launch
// them on a spaceship directly into the sun.
//
// PSD is not my favourite file format.

const int TEN=10; // As if the value of 10 will fluctuate... 

    #Christmas tree initializer  
    toConnect = []  
    toRead =   [  ]  
    toWrite = [    ]   
    primes = [      ]  
    responses = {}  
    remaining = {}  

Примерно в середине страницы 30 xslt

<!-- Here be dragons  -->

в полностью некомментированном методе 2000 строк

{ 
  { 
    while (.. ){ 
      if (..){
          }
      for (.. ){ 
          }
         .... (just putting in the control flow here, imagine another few hundred ifs)
      if(..)   {
            if(..)     {
                   if(..)   {
                ...
                (another few hundred brackets)
                       }
                  }
         } //endif

(На самом деле я однажды снял все скобки, чтобы посмотреть, насколько это плохо, и без форматирования получил следующее:

{{{{}}{}{}{}{}}{{}{{}{}{}{}{}{}{{}{}}{}{}{{}{}{}{}{}{}{}{}{}{}{}{{}}}{{}{{}}{{{}}}{{}{}{}{}{}{}{}{{}}{}{{{}}{}{{}{}}{{{}}{}{}{}{}}{{}}}{}{{}{}{}{{}{{}}{}}{{}}}{{}}{{}}{{}}{}{{}}{{}}{{}}{{}{}{}}{}{}{{{}}{{}}}{}{}{}{}}{{{}{{}{}{}{{}{}{}{}{}{}}{}}{{}}{{}{}}}{{}}{{}}}{{}}{{}}{}{}{}{}{{}}{{}{}{}{}}}}{}{}}{{}{{{}{}{}{}}}}{{}{{{}}}}{{}{{{}{{}}{}{{}}{}{{}{}}{{}}{}{{}}}{{}}}}{{}{}{}{}{}{{{}    {{{{}}{}{}{}{}}{{}{{}{}{}{}{}{}{{}{}}{}{}{{}{}{}{}{}{}{}{}{}{}{}{{}}}{{}{{}}{{{}}}{{}{}{}{}{}{}{}{{}}{}{{{}}{}{{}{}}{{{}}{}{}{}{}}{{}}}{}{{}{}{}{{}{{}}{}}{{}}}{{}}{{}}{{}}{}{{}}{{}}{{}}{{}{}{}}{}{}{{{}}{{}}}{}{}{}{}}{{{}{{}{}{}{{}{}{}{}{}{}}{}}{{}}{{}{}}}{{}}{{}}}{{}}{{}}{}{}{}{}{{}}{{}{}{}{}}}}{}{}}{{}{{{}{}{}{}}}}{{}{{{}}}}{{}{{{}{{}}{}{{}}{}{{}{}}{{}}{}{{}}}{{}}}}{{}{}{}{}{}{{{}{}{{}}{}}}{}}{{}}{{}{}}{{}{{}{{}}}}{{{}{{{}}}}}{{{{{}}}}}{}{}{}{{{{}}}{}{}}{{}{{}}}}{}{{}}{}}}{}}{{}}{{}{}}{{}{{}{{}}}}{{{}{{{}}}}}{{{{{}}}}}{}{}{}{{{{}}}{}{}}{{}{{}}}}

Endif появился около линии 800)

long long ago; /* in a galaxy far far away */ 

//This code sucks, you know it and I know it.  
//Move on and call me an idiot later.

// If this comment is removed the program will blow up