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

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

07.04.2024

Документація

Програмістам важко писати документацію, бо часто документація повторює вже написаний код. Та, писати те ж саме другий раз нудно. Другий — це мінімум: якщо не рахувати план реалізації та тести.

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

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

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

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