Какой наименее полезный комментарий вы когда-либо видели?

Типичные комментарии типа Comp Sci 101:

$i = 0; //set i to 0

$i++; //use sneaky trick to add 1 to i!

if ($i==$j) { // I made sure to use == rather than = here to avoid a bug

Что-то в этом роде.

Незаполненные стандартные комментарии javadoc особенно бесполезны. Они занимают много места на экране, не внося ничего полезного. И хуже всего то, что там, где появляется один такой комментарий, наверняка прячутся сотни других.

/**
 * Method declaration
 *
 *
 * @param table
 * @param row
 *
 * @throws SQLException
 */
void addTransactionDelete(Table table, Object row[]) throws SQLException {

Я уже писал эту маленькую жемчужину раньше:

//@TODO: Rewrite this, it sucks. Seriously.

Обычно это хороший знак, что я подошел к концу сеанса кодирования на ночь.

// remember to comment code

wtf? : D

Что-то вроде этого:

// This method takes two integer values and adds them together via the built-in
// .NET functionality. It would be possible to code the arithmetic function
// by hand, but since .NET provides it, that would be a waste of time
private int Add(int i, int j) // i is the first value, j is the second value
{
    // add the numbers together using the .NET "+" operator
    int z = i + j;

    // return the value to the calling function
    // return z;

    // this code was updated to simplify the return statement, eliminating the need
    // for a separate variable.
    // this statement performs the add functionality using the + operator on the two
    // parameter values, and then returns the result to the calling function
    return i + j;
}

И так далее.

Каждый комментарий, который просто повторяет то, что говорит код, бесполезен. Комментарии не должны рассказывать мне, что делает код. Если я недостаточно хорошо знаю язык программирования, чтобы понять, что происходит, просто прочитав код, мне вообще не следует читать этот код. Комментарии вроде

// Increase i by one
i++;

совершенно бесполезны. Я вижу, что i увеличивается на единицу, это то, что написано в коде, мне не нужны комментарии для этого! Комментарии следует использовать, чтобы объяснить, почему что-то делается (в случае, если это далеко не очевидно) или почему что-то делается именно так, а не каким-либо другим способом (чтобы я мог понимать некоторые дизайнерские решения, принятые другим программистом, которые далеко не сразу очевидны). Дополнительные комментарии полезны для объяснения сложного кода, когда совершенно невозможно определить, что происходит, быстро взглянув на код (например, существуют сложные алгоритмы для подсчета количества битов, установленных в числе; если вы этого не сделаете знаете, что делает этот код, у вас нет шанса угадать, что там происходит).

Однажды я работал над проектом со странным компилятором C. Это давало ошибку в действительном фрагменте кода, если между двумя операторами не был вставлен комментарий. Поэтому я изменил комментарий на:

// Do not remove this comment else compilation will fail.

И это отлично сработало.

Я этому не верю. Я задал этот вопрос после того, как получил 22 ответа, и никто не указал на наименее полезный тип комментария:

комментарии, которые неверны.

Достаточно плохо, что люди пишут лишние комментарии, которые мешают пониманию кода, но когда кто-то пишет подробный комментарий, объясняющий, как что-то работает, и это либо изначально неправильно, либо неправильно после того, как код был изменен без изменения комментария ( гораздо более вероятный сценарий), это определенно худший комментарий.

GhostDoc сам по себе предлагает несколько довольно интересных.

/// <summary>
/// Toes the foo.
/// </summary>
/// <returns></returns>
public Foo ToFoo()

try
{
...some code...
}
catch
{
// Just don't crash, it wasn't that important anyway.
}

*вздох

Попался однажды напильником. Тысячи строк кода, по большей части ужасающий. Плохо названные переменные, сложные условия для циклов и один комментарий, спрятанный в середине файла.

   /* Hmmm. A bit tricky. */

Комментарии по умолчанию, вставленные IDE.

В последнем проекте, над которым я работал и который использовал WebSphere Application Developer, было много разработчиков и подрядчиков по обслуживанию, которых, похоже, не беспокоили сотни, если не тысячи классов Java, которые содержали подобные:

/**
 * @author SomeUserWhoShouldKnowBetter
 *
 * To change this generated comment edit the template variable "typecomment":
 * Window>Preferences>Java>Templates.
 * To enable and disable the creation of type comments go to
 * Window>Preferences>Java>Code Generation.
 */

Всегда была доля секунды между мыслью, что вы действительно нашли хорошо прокомментированный исходный файл, и осознанием того, что, да, это еще один комментарий по умолчанию, который вынудил вас использовать SWEAR_WORD_OF_CHOICE.

Вчера я видел этот комментарий в приложении на C #:

//TODO: Remove this comment.

Мой любимый комментарий на все времена.

/* our second do loop */
do {

Кто бы это ни написал - вы знаете, кто вы.

очень большой проект движка базы данных на C много лет назад - тысячи строк кода с короткими и ошибочными именами переменных и без комментариев ... до тех пор, пока далеко не во вложенных if-условиях несколько тысяч строк в модуле появился следующий комментарий :

//if you get here then you really f**ked

к тому времени, я думаю, мы уже знали это!

В огромном приложении VB5

dim J
J = 0 'magic
J = J 'more magic
for J=1 to 100
...do stuff...

Ссылка явно ЭТО ... и да, приложение без эти две строки не работают во время выполнения с неизвестным кодом ошибки. Мы до сих пор не знаем почему.

Взято из одного из моих сообщений в блоге:

В процессе очистки исходного кода одного из проектов, которым я управляю, я наткнулся на следующие комментарии:

/*
   MAB 08-05-2004: Who wrote this routine? When did they do it? Who should 
   I call if I have questions about it? It's worth it to have a good header
   here. It should helps to set context, it should identify the author 
   (hero or culprit!), including contact information, so that anyone who has
   questions can call or email. It's useful to have the date noted, and a 
   brief statement of intention. On the other hand, this isn't meant to be 
   busy work; it's meant to make maintenance easier--so don't go overboard.

   One other good reason to put your name on it: take credit! This is your
   craft
*/

а затем немного ниже:

#include "xxxMsg.h" // xxx messages
/*
   MAB 08-05-2004: With respect to the comment above, I gathered that
   from the filename. I think I need either more or less here. For one
   thing, xxxMsg.h is automatically generated from the .mc file. That might
   be interesting information. Another thing is that xxxMsg.h should NOT be
   added to source control, because it's auto-generated. Alternatively, 
   don't bother with a comment at all.
*/

а потом еще раз:

/*
   MAB 08-05-2004: Defining a keyword?? This seems problemmatic [sic],
   in principle if not in practice. Is this a common idiom? 
*/

AHHHRRRGGHHH Только что нашел это в каком-то древнем коде, держу пари, парень подумал, что он довольно забавный

private
  //PRIVATE means PRIVATE so no comments for you
  function LoadIt(IntID: Integer): Integer;

Худший комментарий - это неправильное объяснение того, что делает код. Это хуже, чем полное отсутствие комментариев.

Я видел такие вещи в коде со слишком большим количеством комментариев (этого не должно быть, потому что код сам по себе достаточно ясен), и это происходит в основном, когда код обновляется (рефакторинг, модифицированный и т. Д.) но комментарии не обновляются вместе с ним.

Хорошее практическое правило: пишите комментарии только для объяснения почему код что-то делает, а не что он делает.

Определенно должны быть комментарии, которые заменяют обработку ошибок.

if(some_condition){
    do_stuff();
}
else{
    //An error occurred!
}

Я только что нашел вот это, написанное в строке перед закомментированной строкой кода:

//This causes a crash for some reason. I know the real reason but it doesn't fit on this line.

Приложение 100k LOC, которое было перенесено с vb6 на vb.net. Похоже, что предыдущий разработчик поместил заголовок комментария к одному методу, а затем скопировал и вставил точный комментарий к каждому методу, который он написал с тех пор. Сотни методов и каждый неправильно прокомментирован ...

Когда я впервые увидел это, я засмеялся ... 6 месяцев спустя шутка утихает.

Это абсолютно реальный пример из триггера базы данных:

/******************************************************************************
   NAME:       (repeat the trigger name)
   PURPOSE:    To perform work as each row is inserted or updated.
   REVISIONS:
   Ver        Date        Author           Description
   ---------  ----------  ---------------  ------------------------------------
   1.0        27.6.2000             1. Created this trigger.
   PARAMETERS:
   INPUT:
   OUTPUT:
   RETURNED VALUE:
   CALLED BY:
   CALLS:
   EXAMPLE USE:
   ASSUMPTIONS:
   LIMITATIONS:
   ALGORITHM:
   NOTES:
******************************************************************************/

Два самых бесполезных комментария, которые я когда-либо видел ...

try
{
  ...
}
catch
{
  // TODO: something catchy
}

Я также разместил это в Daily WTF, поэтому я обрезал его до комментария ...

  // TODO: The following if block should be reduced to one return statememt:
  // return Regex.IsMatch(strTest, NAME_CHARS);
  if (!Regex.IsMatch(strTest, NAME_CHARS))
    return false;
  else
    return true;

Один, который я никогда не считал очень полезным:

<!--- Lasciate ogne speranza, voi ch'intrate --->

Типичные комментарии типа Comp Sci 101:

Я угрожал своим ученикам случайными актами крайнего насилия, если они когда-либо делали это в заданиях. И они до сих пор сделали. Однако смысл правильного отступа для них, казалось, полностью утрачен. Я думаю, это показывает, почему Python может быть идеальным языком для начинающих.

Комментарии, созданные с помощью инструмента авто-javadoc (например, JAutoDoc). У меня был член команды, отправивший большой объем кода, который был прокомментирован следующим образом:

/**
 * Gets the something
 *
 * @param num The num
 * @param offset The offset
 */
public void getSomething(int num, bool offset)

Может быть, это полезно в качестве отправной точки, но по определению, если программа анализирует имена переменных и методов, чтобы делать свои комментарии, она не может принести много пользы.

У меня их много:

# For each pose in the document
doc.elements.each('//pose') do |pose| ...

# For each sprite in sprites
@sprites.each do |sprite| ...

# For each X in Y
for X in Y do ...

Однако я пытаюсь сократить это количество. :(

Когда я преподаю ООП на C ++ или Java, я обычно получаю следующее:

// My class!
Class myclass 
{
    //Default constructor
    public myClass()
    {
       ...
    }
}

Моя политика - объявить студентам, что они потеряют баллы как за недостаточную, так и за лишнюю документацию.

#include <stdio.h>
//why isn't this working!

С компилятором c, который поддерживает только /*-style */ глобальные комментарии.

Мы поддерживаем ужасный беспорядок в PHP-приложении, и первоначальный разработчик имел привычку оставлять «отладочный код» закомментированным на этом месте. Как он всегда говорил, это произошло потому, что «на случай, если они ему снова понадобятся, он просто раскомментирует их и вуаля, так что это сэкономит ему много работы».

Таким образом, все скрипты буквально пронизаны такими строками, как:

//echo "asdfada";
//echo $query."afadfadf";

Ни один из них на самом деле не работает. В основном они служат для подтверждения того, что выполнение кода достигает этой точки.

Кстати, он никогда не удалял устаревшие скрипты или таблицы базы данных. Итак, у нас есть каталоги, заполненные такими файлами, как dosomething.php, dosomething1.php, dosomething1.bak, dosomething1.bak.php и т. Д. Все боятся что-либо удалять, потому что никто не знает, что на самом деле используется.

Мое исследование посвящено удобству использования API, и я встречал много плохих комментариев просто потому, что они вводят в заблуждение, неуместны, неверны или неполны.

Например, в Java Messaging Service (JMS или в J2EE) класс QueueReceiver.receive содержит следующий драгоценный камень: «Этот вызов блокируется до тех пор, пока не поступит сообщение, не истечет тайм-аут или этот потребитель сообщения не будет закрыт. Тайм-аут, равный нулю, никогда не истекает. и вызов блокируется на неопределенный срок ".

Звучит здорово? правильно?

Проблема в том, что, как показывают мои лабораторные исследования, пользователи считают, что комментарии охватывают все. Столкнувшись с ситуацией, когда сообщения не приходят, они отказываются искать объяснение где-либо еще.

В этом случае, когда вы создаете QueueConnection из QueueConnectionFactory, он сообщает вам, что сообщения не будут доставлены до вызова start. Но это не отображается в методе приема.

Я считаю, что если бы этой линии не было, больше людей искали бы ее в другом месте.

Между прочим, мое исследование посвящено удобству использования JavaDoc в целом и тому, действительно ли люди находят важные директивы в JavaDocs. Если кто-нибудь захочет взглянуть, ссылка на него находится здесь.

У меня есть очень плохая привычка делать это, особенно когда я в ударе:

// TODO: Documentation.

Обрывки посторонних комментариев. Обычно, если есть логическое разделение потока, строка комментариев вроде:

/***************************************************************************/

выше и ниже этого раздела кода могут быть полезны. Это также удобно, когда вам нужно вернуться позже и разделить большую функцию (которая начиналась с малого) на несколько более мелких функций, чтобы код был легко читаем.

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

//-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
//-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=

После каждой строчки кода.

Однажды я увидел в каком-то коде следующий комментарий:

//I know that this is very ugly, but I am tired and in a hurry. 
//You would do the same if you were me...
//...
//[A piece of nasty code here]

Вот два моих любимых:

                // do nothing

На самом деле это не помогает, так как просто занимает место.

Потом где-то дальше:

        // TODO: DAN to fix this.  Not Wes.  No sir.  Not Wes.

Думаю, если я не Дэн или Уэс, мне следует просто проигнорировать это, верно?

cntrVal = ""+ toInteger(cntrVal)      //<---MAYBE THIS IS THE WAY I'M GOING THROUGH CHANGES (comin' up comin' up) THIS IS THE WAY I WANNA LIVE

Кстати, это лирика из песни E-type ...

Чрезмерная избыточность не проясняет, что происходит. Это из прошивки мобильного телефона

/*========================================================================

FUNCTION 
    DtFld_SetMin

DESCRIPTION
    This local function sets a nMin member of the Dtfld struct.

DEPENDENCIES
    None

ARGUMENTS
    [in]me
        Pointer to the Dtfld struct.
    [in]val
        Value to set

RETURN VALUE
    None.

SIDE EFFECTS
    None

NOTE
    None
========================================================================*/
/**
 @brief This local function sets a nMin member of the Dtfld struct..
 @param [in] me  Pointer to the Dtfld struct.
 @param [in]val Value to set
 @retval None 
 @note None
 @see None
*/

static __inline void DtFld_SetMin(DtFld *me, int val)
{
  me->nMin = val;
}

Очень большой исходный файл, реализующий многопоточность в одном процессе. Посреди всех переключений стека вызовов и захвата семафоров, а также приостановки и возобновления потоков был простой комментарий относительно особенно непонятной части манипуляции с указателями:

/* Trickiness */

Ну и дела, спасибо, что поделились.

/* FIXME: documentation for the bellow functionality - and why are we doing it this way */

Это была огромная статистическая программа для бухгалтерского учета. Мы так и не поняли, почему она поступила так - неправильно. Но пришлось его переписать, и заказчику заплатили штраф.

// Magic
menu.Visible = False
menu.Visible = True

Это из инфраструктуры пользовательского интерфейса в некотором коде PowerBuilder, над которым я работал. Фреймворк создавал пункты меню динамически (из данных базы данных). Однако, когда PowerBuilder был обновлен с 16-битной до 32-битной, код меню перестал работать. Ведущий разработчик каким-то образом определил, что скрытие меню с последующим его отображением приводит к его правильному отображению.

Не совсем комментарий, но из JavaDoc, в котором описывается API системы, с которой мне когда-то приходилось работать.

setAttribute(attributeName, attributeValue)
Sets an attribute

Нигде не было задокументировано, что такое атрибут (это не были атрибуты HTML / XML и т. Д.), Какие атрибуты существуют или какие значения они могут иметь.

Однажды я увидел:

#region This is ugly but a mas has to do what a man has to do
Initialization of a gigantic array (...)
#endregion 
// Aren't you glad this has ended?

Я был рад, что не был этим разработчиком.

Я удивлен, что никто не публиковал подобное раньше.

 #contentWrapper{
  position:absolute;
  top: 150px; /*80 = 30 + 50 where 50 is margin and 30 is the height of the header*/
 }

Совершенно неверные комментарии - худший вид комментариев.

Я работаю на двух языках (английском и французском), но мой любимый комментарий был на французском:

/* La passe du coyote qui tousse */

В переводе это будет примерно так:

/* The coughing coyote trick */

Обычно он представлял собой сегмент кода, который либо казался автору умной идеей и был совершенно непонятным, либо это было странное исправление, которое даже автор не понимал, почему он работал (подумайте об исправлении состояния гонки путем перемещения операторов if). Во всех случаях это был плохо написанный код, что пугало любого, кому приходилось его реорганизовывать, потому что было очень трудно предсказать эффект от его изменения.

add ax,1 ;add 1 to the accumulator

шутки в сторону? этот комментарий потратил впустую 5 секунд моей жизни.

также устаревшие комментарии FTL

//the system can only handle 5 people right now. make sure where not over
if(num_people>20){ 

Один из самых забавных, с которыми я когда-либо сталкивался.

// HACK HACK HACK. REMOVE THIS ONCE MARLETT IS AROUND

Тот, который заставил меня задуматься.

// this is a comment - don't delete

// yes, this is going to break in 2089, but, one, I'll be dead, and two, we really ought to be using
// a different system by then
if (yearPart >= 89)
{
    // naughty bits removed....
}

(Бесполезно в качестве комментариев, но оба являются правдивыми заявлениями.)

Я только что видел это в файле INI для программного обеспечения (одного из нескольких, сброшенных на меня не так давно), я поддерживаю:

;--- if LOGERR=1, errors are logged but debugging is difficult
;--- if LOGERR=0, errors are not logged but debugging is easy
LOGERR=1

Что ж, отладка действительно была сложной, но я не решился изменить настройку.

Я бы сказал, что наименее полезный вид комментариев, с которыми я столкнулся, - это комментарии на втором языке.

Я бы предпочел видеть комментарии, написанные четко на чьем-то родном языке, чем нацарапанные на очень плохом приближении к английскому. По крайней мере, тогда его сможет перевести носитель этого языка. Комментарии ESL часто недоступны для чтения всем на планете, кроме человека, который их написал, а иногда даже им.

Взято из унаследованного кода, это было единственное описание назначения следующего if условия (условие занимало 4 строки по 120 столбцов):

#-- Whoa, now that's a big if condition.

Цитирую это по памяти, так что это может быть неточно.

Я не знаю, какого хрена это делает, но похоже, что это работает, поэтому я не трогаю его.

Самое смешное, как я узнал об этом. Этот комментарий был встроен в приложение доступа, написанное одним разработчиком из нашей компании для клиента и распространяемое в MDB. К сожалению, код, который «кажется, работает», провалился, и Access послушно открыл окно кода, при этом отладчик выделил строку прямо под комментарием. У покупателя это не внушало доверия.

Сегодня пробежал через дурак. Я должен был ожидать этого, учитывая, что он был частью макроса VBA в книге Excel.

a.writeline s 'write line

Мне показалось особенно очаровательным, что тот, кто это написал, нашел время, чтобы написать комментарий, в котором использовался пробел, чтобы прояснить невероятно сбивающую с толку беспорядочную команду «Writeline», но не было необходимости использовать осмысленные имена переменных. Лучшее, что я могу сказать, это сокращение от «файл», а s - это сокращение от «String» (потому что «a» уже было занято).

Случайно в середине кода:

//???

Я удалил имя, чтобы избежать затруднений, но это комментарий, найденный в некотором производственном коде. К сожалению, поскольку это был код ASP, относящийся к модулю VB6, и заказчик был весьма любознателен, именно она указала мне на комментарий, когда я был на месте во время визита консультанта. К счастью, она относилась к этому с чувством юмора.

"Я не знаю, как работает этот @"% &. Это набор из & £ $!, Созданный этим подрядчиком ---------.
Я просто оставлю его на месте и надеюсь, что это никому не нужно менять.

К сожалению, для меня код потребовалось изменить примерно через год, после чего мы обнаружили, что у нас не было исходного кода, и нам пришлось выбросить его и переписать бесплатно.

if (someFlag)
{
    // YES
    DoSomething();
}
else
{
    // NO
    DoSomethingElse();
}

Был один парень, который делал это постоянно, остальная часть команды в конце концов убедила его прекратить это делать!

Этот:

Ага, пустое место оставлено как журнал изменений подрывной деятельности.

Я нашел это в примере приложения для картографического продукта:

// Return value does not matter
return 0;

Я нашел это в скрученной программе

# Let them send messages to the world
#del self.irc_PRIVMSG  # By deleting the method? Hello?

Однажды я работал с очень талантливым программистом на ассемблере, который дополнил базовый набор инструкций ARM рядом макросов. Его код состоял из десятков тысяч инструкций и выглядел примерно так - с макро-инструкциями, которые я (компетентный программист ARM) не мог прочитать, представленные ??? и периодические регулярные инструкции ARM, такие как ADD:

...
??? R0,R0,#1
??? R0,R1
ADD R0,R0,#6    ; Add 6
??? R1,R0
??? R0,R0,R1
...

Я могу только предположить, что, когда ваш мозг размером с планету, он слишком высок, чтобы справиться с этими надоедливыми инструкциями, которые просто чертовски просты.

Нашел сегодня в середине блока объявлений:

// other variables

Ну и дела, правда? Спасибо.

Чье-то имя или инициалы и все. Иногда эти подписи определяют блок кода ...

//SFD Start
...code...
//SFD End

Как будто код - это произведение искусства, они должны его подписать! Кроме того, что, если кому-то еще нужно изменить код, отмеченный таким образом?

Это не следует путать с функцией «обвинять» или «аннотировать» в системах управления версиями - они потрясающие!

Однажды я наткнулся на эту маленькую красотку в приложении VB.NET

Dim huh as String 'Best name for a variable ever.

// возврат

return;

Только что нашел это сегодня ...

// TODO: this is basically a copy of the code at line 743!!!

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

/* http://youtube.com/watch?v=oHg5SJYRHA0 */

Классика, над которой мы всегда шутим на моей работе (полная опечаток):

// Its stupid but it work

Это неоднократно обнаруживалось в старой кодовой базе.

Мне пришлось исправить ошибку в 2000 строк кода, которая транскодировала звук из GSM в мю-закон (в основном с использованием битового сдвига и массивов значений преобразования). Единственный комментарий в файле находился в верхней части единственного в нем метода. Это было:

/* Do the business */

Однажды я поддерживал код операционной системы, который мы настроили для миникомпьютера Harris (да, это было давно). Просматривая код планировщика (ассемблера) однажды, я наткнулся на блок кода, который имел комментарий «Begin Magic» вверху и примерно через 25 строк после комментария «End Magic». Промежуточный код был одним из самых сложных, сложных и элегантных, которые я когда-либо видел. Нам потребовалось четверо, чтобы выяснить, что на самом деле делает этот небольшой фрагмент кода (переключение виртуальных машин).

Я вношу некоторые изменения в java-класс, который содержит более 1000 строк, но без комментариев. Я новичок в их стиле кодирования, поэтому не могу удержаться от добавления комментария вроде

/*Added because someone asked me to add it*/

//I am not sure why this works but it fixes the problem.

Это первое место в списке моих бесполезных комментариев.

кто-то прислал мне c-файл, в котором описан двоичный файл, созданный его программой.

он не содержал никаких комментариев, кроме как где-то в записи реальных данных

SwapArray(..); // Big endian ???
write();

Я спросил о реализации SwapArray, и он сказал мне, что он мне не нужен, просто чтобы убедиться, что он работает на машинах с Linux.

После экспериментов я обнаружил, что он везде использовал прямой порядок байтов (что вполне нормально), но только реальные данные были записаны с прямым порядком байтов. Обычно вы могли видеть это в шестнадцатеричном редакторе, но данные хранились с плавающей запятой, поэтому заметить смешанный порядок байтов не так-то просто.

Top of the Pops обязательно должен быть

//  This code should never be called

Мне больше всего понравилось, когда я работал над устаревшим коммуникационным приложением.

// Magic happens here...

Сегодня наткнулся на вот это:

/// <summary>
/// The Page_Load runs when the page loads
/// </summary>
private void Page_Load(Object sender, EventArgs e) {}

Еще один я помню:

//TODO: This needs to be reworked.  THIS CRAP NEEDS TO STOP!!!

{Some Code;} // Не помню, зачем я это делаю, но работает ...

На самом деле у меня их несколько,

// 18042009: (Name here) made me do this

Не очень горжусь этими комментариями, но держу их, чтобы напомнить мне, почему я написал WTF-код именно в этом разделе, что так полезно в этом аспекте.

Я недавно нашел это в коде, который написал много лет назад:

// it's a kind of magic (number)
$descr_id = 2;
$url_id = 34;

Этот комментарий на самом деле был написан на другом языке, но я постараюсь передать эффект в переводе:

//we trick it, if forbidden, as if it had already existed

Комментарий пытался описать то, как он поступал с отключенными элементами списка - код помечает элемент как дубликат, который, следовательно, следует пропустить. Да, очень басовый способ делать что-то, но он бледнел по сравнению с бессмысленным комментарием.

[some code]
// [a commented out code line]
// this line added 2004-10-24 by JD.
// removed again 2004-11-05 by JD.
// [another commented out code line]
[some more code]

а) ПОЧЕМУ? б) Какая линия?

Я увидел потрясающий код внутри AI-части игры:

..."AI code"...
if(something)
   goto MyAwesomeLabel;   //Who's gonna be the first to dump crap on me for this?
..."More Ai code"...

MyAwesomeLabel:
   //It wasn't that hard to get here, right?
   ..."Even more AI code"...

// СРОЧНЫЙ ТОД: Реализуйте это дерьмо заново, старый код чертовски сломан ... и мы думали, что решили все проблемы

Только что нашел это в одном из моих старых проектов. Сначала я рассмеялся, но в конце концов начал скулить, потому что все еще не мог найти ошибку.

Не совсем подходит для вопроса, но я ненавижу, когда вижу:

try
{
  someSeeminglyTrivialMethod();
}
catch (Exception e)
{
  //Ignore. Should never happen.
}

Всякий раз, когда я вижу это во время проверки кода, я говорю им заменить уловку на:

catch (Exception e)
{
  System.exit(0);
}

Я подумал, что это худший комментарий к сообщению SO, и был разочарован, обнаружив обратное.

Прокомментированный код - наименее полезный комментарий :)