README та код

Код чи документація? Чим займатися спочатку? Багато хто вважає, що це питання із серії яйце чи курка, однак, у нашому випадку на нього є досить обґрунтована відповідь.

Код без README

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

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

README без коду

README без коду – об'єкт для плідного обговорення та майже документація. У процесі написання README програміст сам розуміє, що він таки збирається писати. Це дозволяє:

  1. Подумати, не відволікаючись на реалізацію.
  2. Видати прекрасний API знову ж таки не відволікаючись на якісь деталі продажу.
  3. Виявити epic fail ще до написання коду.

Документація - це довго і нудно

До README це не стосується. README не описує у деталях як працює код. У ньому мають бути зібрані прості речі, такі:

  1. Короткий опис, що код взагалі робить.
  2. Опис того, як використовувати його.
  3. Пара прикладів.

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