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

/** function header comments required to pass checkstyle */

GhostDoc придумывает некоторые довольно интересные самостоятельно.

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

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

   /* Hmmm. A bit tricky. */

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

комментарии, которые являются неправильными.

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

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

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

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

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

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

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

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

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

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

// Don't know why we have to do this

Thread.Sleep(1000); // this will fix .NET's crappy threading implementation

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

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

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

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

последний проект я работал, на котором использовал Разработчика приложений WebSphere, имел много разработчиков обслуживания и подрядчиков, которые, казалось, не были побеспокоены сотнями, если не тысячи классов 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.

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

/******************************************************************************
   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:
******************************************************************************/

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

// Increase i by one
i++;

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

Я думал, что это было о худшем комментарии ТАК сообщение и было разочаровано найти иначе.

Я когда-то работал над проектом со странным компилятором C. Это дало ошибку на допустимой части кода, если комментарий не был вставлен между двумя операторами. Таким образом, я изменил комментарий на:

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

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

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

setAttribute(attributeName, attributeValue)
Sets an attribute

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

Как только я видел следующий комментарий в некотором коде:

//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]

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

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

У меня есть многие из них:

# 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 ...

я пытаюсь сократить это, все же.: (

Просто типичная Наука Аккомпанемента 101 комментарий типа:

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

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

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

Звучит великолепно? право?

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

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

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

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

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

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

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

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

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

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

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

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

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

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

После каждая строка кода .

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

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

Я писал этот небольшой драгоценный камень прежде:

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

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

Комментарии сгенерированы auto-javadoc инструментом (например, JAutoDoc). Я сделал, чтобы член команды отправил большой объем кода, который был прокомментирован как:

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

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

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

//TODO: Remove this comment.

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

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