<rmcreative>

RSS

README и код

21 октября 2011

Код или документация? Чем заниматься сначала? Многие полагают, что это вопрос из серии яйцо или курица, однако, в нашем случае на него есть достаточно обоснованный ответ.

Код без README

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

Также, в большинстве случаев отсутствие README — признак того, что код писался либо для себя, что значит решение одной конкретной задачи, либо сходу. Второе хуже, так как даже идеальная реализация неправильной идеи будет работать неправильно.

README без кода

README без кода — объект для плодотворного обсуждения и почти документация. В процессе написания README программист сам понимает, что же он всё-таки собирается писать. Это позволяет:

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

Ну и, конечно, не стоит забывать, что без README каждый новый член команды будет отнимать у автора кода драгоценное время.

Документация — это долго и скучно

К README это не относится. README не описывает в деталях как работает код. В нём должны быть собраны простые вещи, такие:

  1. Короткое описание, что вообще код делает.
  2. Описание того, как его использовать.
  3. Пара примеров.

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

Комментарии RSS

  1. №5525
    Максим
    Максим 21.10.2011, 11:59:16

    Вроде мы как-то обсуждали с тобой это, согласен со всем.

  2. №5527
    idle
    idle 21.10.2011, 15:35:55

    Саш, ты рисуешь равенство между readme и документацией, а это не так. Одно никогда не заменит другое. Да и целенаправленно смешивать их не стоит, впрочем, такое доводится видеть часто.

    _Readme — это аннотация к книге, документация — сама книга. _

    Часто финальная версия readme рождается после написания докуменации, также дела обстоят и с аннотациями.

  3. №5529
    Sam
    Sam 21.10.2011, 17:56:24

    idle, не рисую я равенство. Полная документация определённо не равна README и, в общем-то, охватывает кроме инструкций для конечного пользователя (или программиста, который использует API) ещё и те моменты, которые могут понадобиться при доработке решения.

    Что финальная версия рождается в финале — это понятно. Вопрос в том, что должно быть сначала, черновая версия README или код?

  4. №5534
    idle
    idle 23.10.2011, 18:06:41

    Sam, по-моему так: сначала код с документированием, потом прикидочный readme, документация пользователя, и финальный readme. Выложить код и надеятся на обратную связь можно уже после прикидочного readme.

  5. №5535
    Sam
    Sam 24.10.2011, 2:21:41

    А чем плох вариант начать с README?

  6. №5537
    idle
    idle 24.10.2011, 14:09:16

    Sam, разве только большой вероятностью, что его придётся корректировать/переписывать после написания кода %) Смутно представляю себе достоинства книги, написание которой началось бы с рамок, заданных аннотацией. Так и идея проектировать API в readme кажется мне не слишком удачной. Впрочем, как любил говаривать мой кот своим внукам, выстроившимся полукругом у его кресла-качалки: «На вкус и цвет все тапочки разные».

  7. №5555
    Дмитрий
    Дмитрий 28.10.2011, 4:05:34

    что должно быть сначала, черновая версия README или код?

    Имхо мысль в статье правильная, но содержимое говорит, что автор под "созданием README" видимо понимает процесс проектирования, раз разговор идет о "красивом API" и "эпический фэйлах до реализации". Написание readme (именно в смысле аннотации к будущему коду) ничему подобному не поспособствует. Имхо.

  8. №5556
    Sam
    Sam 28.10.2011, 18:45:38

    А по-моему очень даже способствует. Вот, например.

  9. №5561
    Дмитрий
    Дмитрий 31.10.2011, 15:59:52

    Ну так это уже полноценная документация, а не ридми (аннотация).

  10. №5563
    Sam
    Sam 01.11.2011, 18:44:40

    Разве? По-моему полноценная ещё и алгоритм описывает, чтобы следующая смена разработчиков сразу могла подхватить.

  11. №5570
    idle
    idle 03.11.2011, 7:29:10

    Саш, не забудь, что документация часто подразделяется на два типа: документация пользователя и документация разработчика. Так вот алгоритмы (а также расширенный API и т.п.) описывает вторая. Аннотация же (читай README) нужна общая для продукта. Тип продукта тоже имеет значение для определения рамок документации (ср. низкоуровневую библиотеку и gui-приложение).

    По данной тобой ссылке смесь аннотации и документации — то самое «равно», о котором я говорил в первом комментарии. Первый абзац этого документа должен был вылиться в README, все остальные — в документацию, причем желательно, разбитую по темам.

    Справедливости ради замечу, что в cfile я тоже включил примеры использования расширения в README. И, да, это от лени %)

  12. №5598
    Степан
    Степан 19.11.2011, 22:19:13

    Мне предварительная запись того, что нужно сделать, помогает находить более оптимальные способы решения задач (а не запись помогает делать меня сильней после переделок).

    К примеру:

    1. Сегодня вы записываете как будете решать поставленную задачу, откладываете запись в стол.
    2. Достаем и читаем через 1-3 дня, верим или не верим своим глазам (кто это писал, зачем так делать, если все гениальное просто?), мнем, пишем заново и опять откладываем.
    3. Возвращаемся к пункту 2 до тех пор пока не осознаем, что на данный момент лучшего решения не найти.
  13. №5599
    idle
    idle 20.11.2011, 7:37:02

    @Степан

    И не только вам, однако ни с ридми, ни с документацией сей акт никак не связан.

  1. Почта опубликована не будет.

  2. Можно использовать синтаксис Markdown или HTML.

  3. Введите ответ в поле. Щёлкните, чтобы получить другую задачу.