Чому неправильно коментувати код, а потім поступово видаляти його, щоб відслідковувати, що я вже зробив і що ще потрібно зробити?

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

1. Я коментую весь код, який я підозрюю, що мені доведеться змінити. Я розглядаю коментований код як своєрідний мій список TODO.
2. Я поступово переглядаю коментований код і коментує частини цього коду, або копіюю їх і вставляю в інше місце, а потім редагую їх у міру необхідності або переписую частини цього коду з нуля, дивлячись на коментований код для довідок. Щоразу, коли я думаю, що я закінчую частину коментованого коду, я видаляю його.
3. Я продовжую це, поки не побачу більше коментованого коду.

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

Однак мені сказали, що я повинен припинити це робити. Мені сказали, що замість цього я повинен почати використовувати git, посилаючись на старі коміти, щоб побачити старий код, а не залишати коментований код. Мені сказали:

Коментувати код - це шкідлива звичка, яку слід знищити. Вам не вистачає досвіду, тому ви не розумієте цього. Якщо через кілька років ви побачите код іншої людини, яка любить коментувати код, ви самі почнете лаятися на цю людину. Щоразу, коли я бачу коментований код, я видаляю його в повному обсязі, навіть не дивлячись на нього, тому що зазвичай такий код є абсолютно марним. Ви, звичайно, не побачите недоліків коментування коду в невеликих проектах для однієї людини; але якщо ти знайдеш роботу і збережеш цю звичку там, буде соромно.

Чи можу я запитати, які це недоліки того, що я роблю, що я не бачу зараз?

Треба сказати, що я не дуже захоплююсь лише використанням git, щоб побачити минулий код. Як я вже говорив, коментуючи код, я розглядаю як свого роду тодо-список; в той час як git покаже мені, як виглядав код, він не зможе чітко показати мені, які частини коду ще потрібно переглянути, а які вже зроблено. Я боюся, що я можу пропустити частину коду та ввести помилки.

Для повноти я хочу додати, що людина, яку я цитую, є досвідченим розробником і шанувальником "Чистого коду" дядька Боба - а дядько Боб все-таки критикував, коментуючи різко код у своїй книзі.

Якщо ви врешті-решт видалите весь коментований код, я не бачу з цим реальної проблеми. Залишення коментованого коду у вашій кодовій базі є поганою практикою, але це не те, що ви робите, якщо ви все це працюєте та усуваєте. Я підозрюю, що людина, з якою ви спілкуєтесь, або не розуміє процесу, який ви використовуєте, або є догматичним.

Насправді коментований код нешкідливий. Проблема в тому, що вона безладна і ускладнює читання. Є набагато гірші гріхи, але їх усунути дуже просто. Як особа, яка прокоментувала код, ви зможете визначити, що його можна повністю видалити.

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

Зрештою, роби все так, що найкращий результат для тебе. Навіть якби це був командний проект, поки ви видалите весь коментований код, ви нікого не обтяжуєте.

Чи можу я запитати, які це недоліки того, що я роблю, що я не бачу зараз?

Можливо, жоден, якщо ви працюєте поодинці і не використовуєте контроль версій і вважаєте, що це нормально робити так.

Насправді, без контролю версій не має великого значення, що ви робите в будь-який момент "часу", оскільки код - це завжди будь-який стан, в якому поточний файл "зберігається", як в операційній системі.

Якщо ви користуєтеся контролем версій, і у вас є набір коментарів як "ваш список списку", і ви виправляєте деякі та видаляєте коментар, потім повторюєте, повторюєте і т. Д., Потім у вас "код працює" код і коментарі збережені в історії перегляду Це не буде проблемою, якщо вам ніколи не доведеться повертатися до іншого комітету або навіть "вишневого вибору" пізніше (саме тут ви берете конкретні зобов'язання та перетягуєте їх в іншу гілку, яку слід використовувати). Але в іншому випадку це може бути проблемою.

Можливо, це можна порівняти із "оснащенням кадрів" на жорсткому диску, як у Windows (річ "Відновлення"). Якщо буде зроблено знімок із вірусом у ньому, ви вб'єте вірус, але потім пізніше потрібно відкотитись, ви можете повернутися до точки, де вірус знову присутній.

Такий підхід також може бути проблемою, коли ви використовуєте контроль версій та працюєте з іншими розробниками, оскільки тоді вони повинні бачити ваш список todo, який їм не корисний. Насправді це просто захаращення, що вони повинні ігнорувати і обійтися. У наших колективах ми завжди видаляємо всі коментарі, такі як старий код або "нотатки". Якщо вони не є корисними - проте це дуже рідко, тому що у нас є документація про те, як це працює ", і програмне забезпечення для відстеження того, що потрібно зробити (aka todo).

Крім того, працюючи над більшим проектом, ви прагнете співпрацювати, і виконувати зобов’язання та натискати часто, тому можливо, що їх філія, над якою вони працюють, має ваш список TODO, якщо вони об'єднали вашу філію зі своєю. Тоді ваш список TODO - справа кожного: D

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

І це в деяких аспектах це особиста річ, але використання кодової бази як вашого "списку todo" насправді не ідеально. Одного разу ви можете залишити щось випадково, або забути прокоментувати це або прокоментувати його помилково.

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

Здається, ваш рецензент трохи догматичний. Я не впевнений, що присягається комусь за коментування коду - це ПК ;-) або навіть корисний ;-)

Але якщо серйозніше, я вважаю, що ваш рецензент правильний, що ви повинні серйозно розглянути можливість використання git (або якоїсь іншої системи управління джерелами, але git - це розумний вибір).

І це може полегшити деякі ваші потреби коментувати код.

Але наявність списку TODO всередині коду (чи букет списків, чи старий код) - на мою думку, цілком розумно. Але ви, можливо, захочете трохи переглянути, як це зробити. З одного - я пропоную подумати над тим, щоб хтось ще прочитав ваш код. Щоб хтось інший міг бути ти, через рік після того, як ти кинеш і знову приєднаєшся до проекту. Або це може бути хтось інший цілком. ВЖЕ зустрічатися з коментованим кодом трохи заплутано. Можливо, щось на кшталт:

/*
 * Need this sort of functionality added back before too long:
 * .... OLD CODE HERE
 */

Особисто я більше схиляюся до чогось такого:

 * TODO:
 *      @todo   Possible get rid of intermediate LRUCache_ object.
 *
 *      @todo   Find some reasonable/simple way to get
 *              LRUCache<PHRShortcutSpec, PHRShortcutSpec, PHRShortcutSpecNoAuthCacheTraits_>   sRecentlyUsedCache (kMaxEltsInReceltlyUsedCache_);
 *              Working with ONE T argument
 *              Add(elt2cache).
 ...

і я сміливо ввожу "фрагменти коду" зі старого коду як корисні.

Використовувати git важко (на жаль). Навчання вам знадобиться певний час, і вам може здатися, що це не є частиною того, що ви намагаєтеся досягти. Але якщо ви збираєтеся програмувати корисно, вам потрібно буде навчитися робити це як частина команди, і спілкування з командою, і git - це саме так, як це робиться сьогодні. І як тільки ви звикли до його використання, ви знайдете ДУЖЕ корисний інструмент / милицю, що полегшить розробку програмного забезпечення.

Удачі!

Є багато причин коментувати код: -

• Це ще не правильно, і ви відмените коментар, коли він буде готовий.
• Ви тимчасово коментуєте це, щоб змінити поведінку під час налагодження.
• Ви не впевнені, чи потрібен код, але не хочете видаляти його, поки ви ще не протестували.
• Код потрібен для деяких версій програмного забезпечення, але не для цієї.
• Код застарілий, але для написання потрібні століття, і ви до нього емоційно прив’язані. Крім того, це може бути корисним одного дня.

Проблема виникає, коли ви кладете код спати, а потім повертаєтесь до нього через пару років, щоб зробити певне обслуговування. Ви знайдете кодову базу, залиту коментованим кодом. Більше не буде зрозуміло, чому все там є, і зараз це просто захаращено.

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

Я не збираюсь повторювати, чому ви повинні використовувати контроль над джерелами навіть для проектів на одну особу, оскільки там багато інших ресурсів, які підкажуть вам це зробити. Але одним із важливих недоліків вашого поточного підходу є те, що якщо ви коментуєте код, ви ховаєте його від свого IDE (якщо ви не використовуєте IDE, ви, ймовірно, повинні це врахувати).

Наприклад, якщо ви хочете перейменувати метод або клас або змінити кількість параметрів, який приймає метод, у вашому IDE має бути зроблений параметр рефактора, який знайде всі відповідні посилання та оновить їх відповідно - але він, ймовірно, виграв ' t пошук в коментарях.

Замість того, щоб намагатися вгадати, де потрібно вносити зміни, просто внесіть їх у відповідь та дозвольте вашій IDE повідомити, де ваші зміни спричинили зламування. Потім ви можете прокоментувати код більш хірургічним шляхом та, сподіваємось, за коротший проміжок часу, перш ніж виправити будь-яку помилку.

Це погано, і ти повинен зупинитися .

Причина зводиться до спроби зробити велику кількість рефакторингу за один раз.

Якщо ви коментуєте великі розділи коду, трохи поправте і зареєструйтесь, тоді ви зареєстрували нефункціональний код. і цілий набір коментованих матеріалів, які інші вважатимуть, є старим і може бути ігнорований

Якщо ви не заїжджаєте часто, ви накопичуєте конфлікти злиття і не записуєте крок за кроком.

Потрібно змінити свою робочу практику так, що якщо вам доведеться зупинитись на середині, все все ще працює.

Зробіть дитячі кроки та заїжте після кожного:

• витягнути інтерфейс
• написати тест
• рефактор функція

Не відзначайте великі шматки коду як "ваші", коментуючи їх, і відводьте їх, щоб вони над собою працювали, поки вони не завершаться або ви не зможете.

Якщо вам потрібно відстежувати, що потрібно зробити, використовуйте дошку завдань, наприклад, scrum або trello