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

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

//TODO translations

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

В моей отрасли разработчикам рекомендуется делать записи 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.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

ConnManager.getConnection(GetDatabaseName());

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

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

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

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

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

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

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

Мои 2 цента

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

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

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

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

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

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

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

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

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

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

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

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

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

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

в Дельфи:

{$message 'todo: free this thing when you know its not going to blow up'}

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

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