Стендап Сьогодні 📢 Канал в Telegram @stendap_sogodni

🤖🚫 AI-free content. This post is 100% written by a human, as is everything on my blog. Enjoy!

10.04.2025

Коли та як документувати код?

Потрапив мені в пазури чужий проєкт, на якому документація коду (тобто коментарі) зроблена так, що я позаздрив.

Чому? Бо кожний клас та кожний атрибут був пояснений влучно, але не багатослівно. Рівно стільки, щоб зрозуміти, що він робить. Всупереч цьому, зазвичай я бачу приблизно нуль документації, а коли її все ж багато, то вона скочується в тавтології на кшталт “ID це ідентифікатор продукту”.

Тоді коли корисним коментарем було б (уявне) “ID продукту, унікальний в межах облікового запису” - тобто щось таке, що код нам прямо не скаже, але ми б хотіли дізнатися.

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

Тому гадаю, принаймні варто “досолити в тарілці” - записувати ті знахідки, які знайшлися під час повернення до коду. Або поки пояснюєш, як воно працює, комусь іншому. Бо саме на цьому етапі зʼявляється вище розуміння що “аби це було написано, не довелося б залазити в абсолютно інший шар коду, щоб зрозуміти, звідки то значення береться”.

Ну як мінімум — обовʼязково фіксую, коли спробував щось поміняти, але не вийшло через несподівані обставини. Але то вже класичний жанр.