Код или документация? Чем заниматься сначала? Многие полагают, что это вопрос из серии яйцо или курица, однако, в нашем случае на него есть достаточно обоснованный ответ.
Код без README
Код без README бесполезен, так как не ясно, какую задачу он решает и как им пользоваться. Даже свой код со временем начинает забываться. При работе в команде без документации совсем плохо. Для открытого кода без README просто нельзя.
Также, в большинстве случаев отсутствие README — признак того, что код писался либо для себя, что значит решение одной конкретной задачи, либо сходу. Второе хуже, так как даже идеальная реализация неправильной идеи будет работать неправильно.
README без кода
README без кода — объект для плодотворного обсуждения и почти документация. В процессе написания README программист сам понимает, что же он всё-таки собирается писать. Это позволяет:
- Подумать, не отвлекаясь на реализацию.
- Выдать красивый API опять-же не отвлекаясь на какие-то детали реализации.
- Выявить epic fail ещё до написания кода.
Ну и, конечно, не стоит забывать, что без README каждый новый член команды будет отнимать у автора кода драгоценное время.
Документация — это долго и скучно
К README это не относится. README не описывает в деталях как работает код. В нём должны быть собраны простые вещи, такие:
- Короткое описание, что вообще код делает.
- Описание того, как его использовать.
- Пара примеров.
Если README пишется в самом начале, пишется он легко, потому как рутина ещё не сбила всё желание. Если же делать наоборот, писать ещё и README будет ну совсем невмоготу.
