Ви пишете заголовки в кодових коментарях? [зачинено]

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

/*Board initialization*/
...code...

/*Player initialization*/
...code...

/*Game logic starts here*/
/*Displaying current situation*/
...code...

/*Executing move*/
...code...

/*Handle special event*/
...code...

/*Commit changes, switch to next player*/
...code...

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

Це кодовий запах. Це говорить, що і ні чому .

Якщо це необхідно, розділіть код на невеликі функції.

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

Мені цікаво, як багато людей не люблять цю практику, не маючи можливості сформулювати чому. Причини подібних коментарів нахмурені - це ознака того, що ви порушили принцип єдиної відповідальності. Ця конкретна назва зазвичай використовується лише в контексті ОО, але загальне поняття також називається згуртованістю і стосується інших парадигм. Школи зазвичай не навчають подібних принципів дизайну до кінця програми навчання, якщо взагалі немає. Насправді, деякі вчителі призначають її порушення, щоб полегшити оцінку, скомпірувавши все в один файл. Тому ваше невігластво першокурсника є виправданим, і те, що ви помітили "щось" не так і намагалися уточнити за допомогою коментарів, навіть є похвальним за обставин, але загалом краще виправити незрозумілу конструкцію, а не намагатися надрукувати її з коментарями.

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

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

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

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

Я вважаю, що частина мого схильності до цього полягає в тому, що моя програма є досить статистичною, тому вона дещо повторюється. Тоді як, можливо, є кілька фрагментів коду, де я шукаю функцію корисної назви, я можу мати кілька десятків досить схожих застосувань чогось на зразок загальної функції лінійної моделі. Корисно мати змогу дізнатися, хто з них був "наскільки чутливими є результати для вибору A проти вибору B або C", а який був чимось іншим. Це часто прискорюється назви.

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