Имеют ли смысл комментарии TODO? [закрыто]

86

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

//TODO translations

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

Имеет ли смысл писать эти комментарии или они должны быть написаны на доске / бумаге / чем-то еще, где они остаются в центре внимания разработчиков?

Ivan Crojach Karačić
источник
2
(некоторые) IDE отслеживают это. Я использую их свободно, когда полностью не реализовал реализацию модуля, но для меня (или других) контракт удовлетворителен для продолжения разработки другого связанного компонента.
smp7d
3
TODO для меня больше похоже на «должны оптимизировать, но не нужно отправлять»
Джейк Бергер
8
Всякий раз, когда я думаю о задаче, которую нужно выполнить, или о крайнем случае, который необходимо проверить на текущую функцию, над которой я работаю, я прекращаю писать то, что пишу (даже в середине инструкции), и добавляю для этого TODO (даже если это просто строка выше) . Это помогает предотвратить те "О да, я даже думал об этом" ошибки. Прежде чем зафиксировать эту функцию, я проверяю TODO. Они никогда не становятся преданными, но с тех пор, как я начал это делать, количество ошибок значительно сократилось .
BlueRaja - Дэнни Пфлюгофт
8
Я всегда использую, #warning TODO: …если я не хочу забывать TODO.
вправо
2
@WTP: Visual Studio, R #, Netbeans, Eclipse и т. Д. И т. Д. - все они содержат инструменты для просмотра всех TODO в рамках решения / рабочей области. Больше нет необходимости в этом старом взломе.
BlueRaja - Дэнни Пфлугхофт

Ответы:

107

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

Я также уверен , что я гоняться на них - я их поиск (Visual Studio имеет хорошую особенность , где он будет перечислять такие комментарии для вас) и убедитесь , что все будут сделаны.

Но, как вы говорите, не все прилежны к ним и, как и многие комментарии, со временем имеют тенденцию гнить.

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

Одед
источник
18
Eclipse выделяет их и объединяет их список для вас. И написание комментария TODO, в то время как мысль у вас на уме, не плохая идея, даже если вам никогда не удавалось на самом деле это делать. Некоторая великодушная душа может на самом деле просматривать код в поисках того, что нужно сделать (OSS).
варенье
4
У Resharper также есть хороший список TODO, он работает лучше, чем стандартный VS (выглядит в большем количестве файлов).
CaffGeek
Да, учитывая список в вашей IDE, они полезны. В противном случае я бы сказал, что они очень ограничены в использовании, поскольку кодовая база может быть огромной.
инженер
4
Из-за гнили комментариев, я всегда датирую и начинаю свои комментарии. Если комментарий от трех подрядчиков три года назад, вы, вероятно, можете его удалить.
user1936
2
Поскольку были упомянуты resharper и даты, я использую простой Resharper Live Template из "// TODO $ user $ ($ date $) -"
dark fader
56

Современные IDE распознают TODOкомментарии, и они как таковые видны в своих собственных панелях / окнах / вкладках, поэтому они теоретически не потеряны (я думаю, Eclipse и Visual Studio, и я знаю достаточно, чтобы помнить, что они их распознают).

Вы даже можете настроить дополнительные комментарии, например FIXME, BEWAREили что-либо еще, что вы хотите настроить. Тем не менее, другие разработчики вашего проекта должны будут настроить свою IDE таким же образом.

Теперь я написал «теоретически», потому что, хотя он и не потерян, TODO чаще всего относится к тому, что не требуется для правильной работы приложения «на данный момент». А «на данный момент» может продлиться от 5 минут до 5 лет, в зависимости от типа / размера проекта :-)

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

Изменить: Как написано в статье Википедии о комментариях , включая хорошую дату и владельца TODO считается хорошей практикой.

оборота Жалайн
источник
32
Я думаю, что дата и владелец TODO просто шум. Вот для чего нужен контроль версий (и функция обвинений) (если вам действительно нужна информация).
слеске
3
Я не думаю, что википедия с надписью «Рекомендуется» является какой-либо цитатой; бдительный запах Лучшая ссылка на статью, которая утверждает это.
Phresnel
@ phresnel, ну, есть цитата, связанная с этим «советом», поэтому я не чувствовал необходимости повторять это здесь, иначе я согласен с тем фактом, что цитирование фактов Википедии, не подкрепленных ничем, может быть опасным
Jalayn
@sleske Я бы предпочел согласиться с тем, чтобы шум был минимальным, НО я думаю, что IDE не предоставляют автоматически эту информацию из хранилища (если я не ошибаюсь, вам придется сравнивать версии вручную), если вы явно не пишете ее ,
Джалайн
1
Функция аннотирования в Visual Studio позволяет легко определить, кто в последний раз проверял изменения в различных частях файла, над которым вы работаете, и с помощью какого набора изменений. Не идеально, но во многих случаях (особенно с TODOкомментариями) достаточно близко, чтобы быть полезным.
CVN
13

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

Например, «быстрые и грязные» решения удобно маркировать, например:

ConnManager.getConnection("mydatabase"); // FIXME: DB name should be configurable

Если код делает то, что должен, и никто не жалуется, то комментарий не причинит вреда. Если когда-нибудь будет время украсить код, легко начать поиск FIXMEметок.

Joonas Pulakka
источник
3
«FIXME» и «TODO» имеют для меня разные значения. Перевод, жестко запрограммированное значение или исключение ex.printStacktrace()- это TODO для меня. С другой стороны, FIXME будет иметь дело с Исключением, которое иногда возникает, утечкой памяти или другим типом ошибки, которую вы обнаружили, но не полностью проанализировали / исправили.
выстр
10

В моей отрасли разработчикам рекомендуется делать записи JIRA (или других) вместо комментариев todo, потому что не у всех есть шанс увидеть // todoзаписи. Но иногда в больших проектах настраиваемый атрибут определяется следующим образом:

[AttributeUsageAttribute(AttributeTargets.All, AllowMultiple = true)]
public class DeveloperNote : Attribute
{
    public DateTime EntryDate { get; set; }
    public string Description { get; set; }
    public DeveloperNote(int year, int month, int day, string desc)
    {
        EntryDate = new DateTime(year, month, day);
        Description = desc;
    }
}

И тогда метод может быть оформлен таким образом ...

[DeveloperNote(2011, 12, 13, "Make the db connection configurable")]

И высшие взлеты могут прийти и собрать их автоматически. Это может быть излишним для простого // todoнапоминания, но это эффективно. Также требуется платформа .NET.

Garry
источник
5
Комментарий TODO lcoalized к строке для кода. Билет более глобальный и более высокий уровень, на мой взгляд. И я думаю, что эта аннотация является излишним. У TODO больше шансов работать с большим количеством редакторов.
выстр
6
Ваша индустрия? Что это? Я не знаю целую индустрию, которая поощряет использование JIRA ?!
Френель
7

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

В прошлом году мне позвонили, что часть моего кода была удалена. Я был довольно впечатлен, что он был в производстве и пережил обслуживание в течение 16 лет. Так что имейте в виду, ваш код может длиться долго. Комментарии о намерениях, будущих потребностях и т. Д. Могут в значительной степени помочь кому-то через несколько лет, кто смотрит на ваш код впервые.

Пит Манчини
источник
1
Если он был там более десяти лет, он не был действительно необходим, и поэтому добавление TODOкомментариев не имело смысла.
CVn
2
Это предполагает, что они никогда не меняются. Как и в коде, комментарии могут быть изменены с добавлением, удалением и модификациями. Списки TODO, скорее всего, будут изменены таким образом. Я уверен, что за последнее десятилетие, с тех пор как я в последний раз коснулся кода, его комментарии были изменены.
Пит Манчини
6

По моему опыту это зависит. Основным фактором является то, достаточно ли дисциплинирована команда, чтобы следить за этими «маленькими» комментариями. Если они это делают, то да, они имеют смысл. Если они этого не делают, то эти комментарии - просто пустая трата времени, и вы, возможно, захотите посмотреть другие варианты, например, карты рассказов.

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

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

Manfred
источник
6

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

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

Чтобы помочь мне, наши сборки CI настроены на неудачу, если в коде есть FIXME :-).

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

При желании вы можете вставить TODO с идентификатором ошибки :-).

sleske
источник
3

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

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

ConnManager.getConnection("mydatabase"); // FIXME: DB name should be configurable

вы можете изменить это на что-то вроде

ConnManager.getConnection(GetDatabaseName());

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

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

Что же касается в том числе программист имя / подпись с комментарием, я думаю , что это перебор , если у вас есть система исходный код версии управления (вы сделать , верно?). В этом случае его функция обвинения скажет вам, кто добавил комментарий, или, точнее, кто в последний раз зарегистрировал изменение, которое коснулось комментария. Например, в Visual Studio это легко сделать с помощью функции «Аннотация», которая есть среди функций управления исходным кодом.

CVn
источник
3

Если вы напишите TODO или FIXME с идеей, что кто-то еще исправит это, когда придет к этому коду в неопределенном будущем, то я бы сказал, не беспокойтесь. Они будут засорять код и загромождать отчетную часть вашей IDE, которая собирает эту информацию.

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

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

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

Мои 2 цента

оборота ньютопия
источник
2

Обычно я не делаю комментарии // TODO, но храню их все в отдельном файле. Все еще не могу найти / написать онлайн-программное обеспечение, чтобы легко управлять ими, поэтому файлы TODO по-прежнему наиболее полезны для меня, потому что, когда я открываю проект даже спустя короткое время, я забываю, что делать сейчас, а затем смотрю в файл TODO и выполняю работу. , У меня есть «filename.cpp 354: перекодировать этот бла-бла-бла», и это гораздо полезнее, чем поиск // TODO комментариев в файле. Я сделал // TODO раньше, когда мне было лень, но я просто удаляю эти старые // TODO из исходного файла и не исправляю их, когда проект работает хорошо. Я настоятельно рекомендую переместить все // TODO из источника в отдельное место и хранить их вместе с другими задачами, чтобы вы могли легко расставлять приоритеты для задач. Приоритет - действительно сложная задача, когда вы получаете все свои TODO в различных файлах и различных проектах.

CND
источник
7
И затем вы вставляете новую функцию в filename.cpp, скажем, около 200 строки в случае вашего примера, потому что вы находите полезным реорганизовать какой-то фрагмент кода. Вдруг ваша ссылка бессмысленна. Я предпочитаю, чтобы IDE указывал мне на то, где они сейчас находятся , а не на то, где они были, когда я в этом нуждался TODO.
CVN
Да, вы правы) Иногда мне трудно найти линию, но я с этим справляюсь. И да. Я могу использовать оба, чтобы легко найти в файле или IDE, но чтобы знать, что делать в отдельном месте.
CND
2

Я думаю там здорово, но не в одиночку. Например:

//TODO: ADD MY CLICK EVENT LOGIC
throw new Exception();
//Even a simple messageBox could suffice

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

Эдвард
источник
2
В этом случае вы можете просто бросить, new NotImplementedException()что подразумевает задачу.
CodesInChaos
В CI любят использовать assert(0 && "TODO[cmaster]: Add click event logic");. Простой и очень эффективный
способ
1

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

Вероятно, более подходящим местом для подобных вещей является трекер, а не код.

Уайетт Барнетт
источник
0

Я настоятельно рекомендую вносить каждый TODO или FIXME в официальный журнал. Если это не так, они легко доступны для поиска, и в каждой итерации должна быть фаза проверки на наличие выдающихся TODO и FIXME. Затем они могут быть внесены в каталог и настроены на немедленное устранение, или команда может запланировать их исправление в соответствующее время.

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

Итог: они лучше, чем вообще не регистрируют проблемы, но на самом деле их нужно поддерживать.

Marcin
источник
-1

IntelliJ на самом деле предупредит вас, если вы попытаетесь зафиксировать код с новыми TODO. Таким образом, вы всегда можете интерпретировать TODO как «это действительно должно произойти ко времени, когда я сделаю коммит».

ripper234
источник
-1

Когда вы рассматриваете «TODO» как семантическую метку для вашего комментария, я думаю, что они имеют смысл.

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

Полезно, что многие IDE могут быть сконфигурированы для добавления этих комментариев в список задач, что позволяет обрабатывать их аналогично для создания изменений и не забывать бесконечно.

Стюарт
источник
-2

Более отвратительный, но эффективный метод, вероятно, состоит в том, чтобы превратить ваши todo-комментарии в сообщения компилятора, чтобы вы и все остальные видели это при компиляции программы.

в Дельфи:

{$message 'todo: free this thing when you know its not going to blow up'}
Питер Тернер
источник
-4

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

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

Мартин Джамбон
источник
это только ваше мнение или вы можете как-то это подтвердить?
комнат
Это мое мнение и совет, основанный на моем опыте. Некоторые люди используют комментарии TODO, чтобы сказать: «Я знаю, как писать хороший код, но я не собираюсь этого делать, потому что мне все равно, но эй, я написал TODO здесь, так что это действительно показывает, что я знаю, как писать чистый код».
Мартин Джамбон