Чи мають сенс коментарі 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 Earler, коли мені було лінь, але я просто видаляю ці старі // TODO-s з вихідного файлу і не виправляю їх, коли проект працює добре. Я настійно рекомендую перенести всі // 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 можуть бути налаштовані на додавання цих коментарів до списку завдань, що дозволяє їм поводитися аналогічно, створювати wrnings і не забувати нескінченно.

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

у Delphi:

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

На мій досвід, його TODOслід використовувати, щоб вказати, що фрагмент коду не є корисним, і повідомляє читачеві, що потрібно, щоб зробити його корисним (як локально, так і деінде).

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