README и код
21 октября 2011
Код или документация? Чем заниматься сначала? Многие полагают, что это вопрос из серии яйцо или курица, однако, в нашем случае на него есть достаточно обоснованный ответ.
Код без README
Код без README бесполезен, так как не ясно, какую задачу он решает и как им пользоваться. Даже свой код со временем начинает забываться. При работе в команде без документации совсем плохо. Для открытого кода без README просто нельзя.
Также, в большинстве случаев отсутствие README — признак того, что код писался либо для себя, что значит решение одной конкретной задачи, либо сходу. Второе хуже, так как даже идеальная реализация неправильной идеи будет работать неправильно.
README без кода
README без кода — объект для плодотворного обсуждения и почти документация. В процессе написания README программист сам понимает, что же он всё-таки собирается писать. Это позволяет:
- Подумать, не отвлекаясь на реализацию.
- Выдать красивый API опять-же не отвлекаясь на какие-то детали реализации.
- Выявить epic fail ещё до написания кода.
Ну и, конечно, не стоит забывать, что без README каждый новый член команды будет отнимать у автора кода драгоценное время.
Документация — это долго и скучно
К README это не относится. README не описывает в деталях как работает код. В нём должны быть собраны простые вещи, такие:
- Короткое описание, что вообще код делает.
- Описание того, как его использовать.
- Пара примеров.
Если README пишется в самом начале, пишется он легко, потому как рутина ещё не сбила всё желание. Если же делать наоборот, писать ещё и README будет ну совсем невмоготу.
Комментарии RSS по email OK
Вроде мы как-то обсуждали с тобой это, согласен со всем.
Саш, ты рисуешь равенство между readme и документацией, а это не так. Одно никогда не заменит другое. Да и целенаправленно смешивать их не стоит, впрочем, такое доводится видеть часто.
_Readme — это аннотация к книге, документация — сама книга. _
Часто финальная версия readme рождается после написания докуменации, также дела обстоят и с аннотациями.
idle, не рисую я равенство. Полная документация определённо не равна README и, в общем-то, охватывает кроме инструкций для конечного пользователя (или программиста, который использует API) ещё и те моменты, которые могут понадобиться при доработке решения.
Что финальная версия рождается в финале — это понятно. Вопрос в том, что должно быть сначала, черновая версия README или код?
Sam, по-моему так: сначала код с документированием, потом прикидочный readme, документация пользователя, и финальный readme. Выложить код и надеятся на обратную связь можно уже после прикидочного readme.
А чем плох вариант начать с README?
Sam, разве только большой вероятностью, что его придётся корректировать/переписывать после написания кода %) Смутно представляю себе достоинства книги, написание которой началось бы с рамок, заданных аннотацией. Так и идея проектировать API в readme кажется мне не слишком удачной. Впрочем, как любил говаривать мой кот своим внукам, выстроившимся полукругом у его кресла-качалки: «На вкус и цвет все тапочки разные».
Имхо мысль в статье правильная, но содержимое говорит, что автор под "созданием README" видимо понимает процесс проектирования, раз разговор идет о "красивом API" и "эпический фэйлах до реализации". Написание readme (именно в смысле аннотации к будущему коду) ничему подобному не поспособствует. Имхо.
А по-моему очень даже способствует. Вот, например.
Ну так это уже полноценная документация, а не ридми (аннотация).
Разве? По-моему полноценная ещё и алгоритм описывает, чтобы следующая смена разработчиков сразу могла подхватить.
Саш, не забудь, что документация часто подразделяется на два типа: документация пользователя и документация разработчика. Так вот алгоритмы (а также расширенный API и т.п.) описывает вторая. Аннотация же (читай README) нужна общая для продукта. Тип продукта тоже имеет значение для определения рамок документации (ср. низкоуровневую библиотеку и gui-приложение).
По данной тобой ссылке смесь аннотации и документации — то самое «равно», о котором я говорил в первом комментарии. Первый абзац этого документа должен был вылиться в README, все остальные — в документацию, причем желательно, разбитую по темам.
Справедливости ради замечу, что в cfile я тоже включил примеры использования расширения в README. И, да, это от лени %)
Мне предварительная запись того, что нужно сделать, помогает находить более оптимальные способы решения задач (а не запись помогает делать меня сильней после переделок).
К примеру:
@Степан
И не только вам, однако ни с ридми, ни с документацией сей акт никак не связан.