Comments 36
UFO just landed and posted this here
Документирование в readme мало чем отличается от комментирования на уровне методов, на уровне классов или пакетов. Как и в случае с комментариями — если в вашем проекте есть readme файл, то значит в нем еще достаточно возможностей, для улучшения.
В целом же, товарищ Tom Preston-Werner, похоже, слабо понимает принципы и ценности, например, XP, где основная идея — как разрабатывать софт так, чтобы он соответствовал пожеланиям клиентов.
В целом же, товарищ Tom Preston-Werner, похоже, слабо понимает принципы и ценности, например, XP, где основная идея — как разрабатывать софт так, чтобы он соответствовал пожеланиям клиентов.
Вообще-то идея в том, чтобы писать Readme до того, как начинать кодировать. Это значит, что ещё нет ни кода, ни, соответственно, комментариев.
На мой взгляд, эта идея вполне соответствует принципу agile «Непосредственное общение является наиболее практичным и эффективным способом обмена информацией как с самой командой, так и внутри команды.»
На мой взгляд, эта идея вполне соответствует принципу agile «Непосредственное общение является наиболее практичным и эффективным способом обмена информацией как с самой командой, так и внутри команды.»
Наиболее практичным способом обмена информацией с командой является «взять и пообщаться с командой», а не сгенерировать документ, который потом необходимо поддерживать. Зафиксировать принятые дизайн решения лучше будет в тестах.
Согласен, «пообщаться с командой» — это самый эффективный вариант. Правда он не всегда работает, как например, в случае, если члены команды находятся в разных часовых поясах.
Ну да, и по каждому пустяку общаться? Зачем? Если можно сделать Doxygen-like документацию и минимизировать общение членов команды, по вопросам, которые могут быть решены наличием документации.
По какому пустяку?
Непонятность назначения определенных частей кода, к примеру
В этом случае необходимо делать рефакторинг, а не писать комментарии, объясняющие плохо написанный код. Мало того, что это накапливающийся технический долг, так еще и комментарии устареют и будут врать через 3-4 итерации.
Вы случайно не из той категории программистов, которые утверждают, что комментарии в коде это лишнее?
Комментарии полезны если описываешь public API и не показываешь код. Но у них другое предназначение, этот кейс я упоминал ниже в одном из комментариев. Ок, еще полезны в парочке экзотических случаев. В большинстве же своем комментарии пишут там, где нужно было бы просто подумать над именами и разделить по функциям. В том числе, когда код не понятен.
Комментарии полезны если описываешь public API и не показываешь код
Вам не кажеться, что в любом случае стоит описывать публичный интерфейс если он не является тривиальным?(например: кидает исключения, выполняет какую-то специфическую операцию имя которой сложно впихнуть в имя функции и т.д.)
Меня комментарии часто выручали, даже в собственном коде. Например когда разбираешь формат файла какой-нибудь программы с кучей эмпирически полученных констант. Да уже через месяц не вспомнишь кк эти константы были вычислены и откуда они взялись.
У меня много примеров, когда комментарии были бы очень к месту и их там не было. И очень мало примеров, когда комментарии повторяли код.
Нет, не кажется. Если он кидает исключение — в Java это документируется throws декларацией. Могу прокомментировать и специфическую операцию, и константы, если будет пример. Я понимаю весь скептицизм, сам такой был, пока не показали, как действительно можно писать самодокументирующийся код и не поводили за ручку, тыкая в разные места приговаривая «э-э-э, зачем комментарий, сделай вот так!».
Если вам потребовалось что-то комментировать, то лучше сразу переписать непонятный кусок кода так, чтобы было сразу понятно, что и как работает. Созданы тысячи способов как написать не говнокод
И все эти тысячи способов разлетаются в пух и прах при столкновении с реальностью.
Действительно, способы то есть. Но где гарантия, что не нарушился функционал? — Тестирование. Если затраты на этот производственный цикл существенно превышают затраты на оставление коментария (что чаще всего бывает), то к рефакторингу редко прибегают, если система уже емкая по функционалу…
Накладные расходы на тестирование не идут ни в какое сравнение с будущими расходами на переписывание огромного куска года, который с годами обростает такими костылями, что проще выкинуть и переписать заново. Так вот, переписывание заново в основном идет за счет разработчика. А рефакторинг легко производится за счет заказчика.
Не оставляйте даже минимальную затравку говнокода, она имеет свойство разрастаться и заражать остальные участки кода.
Не оставляйте даже минимальную затравку говнокода, она имеет свойство разрастаться и заражать остальные участки кода.
Да нет, как раз комментирование на уровне методов — это совсем не то же самое, что readme.txt. Файл readme — он для пользователей, а не для программистов. Пользователям глубоко неинтересно внутреннее устройство приложения, названия методов, иерархия классов, типы переменных… Это все можно описывать в документации, чтоб другим программистам было легче потом с этим кодом работать. А пользователям — им нужно знать что делает ваша программа, как ею пользоваться и какие проблемы она помогает решить. Все.
Если пользователю требуются что-то прочитать, чтобы понять, как оно работает или как его запустить — значит юзабилити программы можно улучшить либо упростить способ установки/запуска. В идеале пользователь ничего не читает, а может пользоваться программой с первых секунд.
Сильно зависит от решаемой задачи.
Если задача тривиальная (простой калькулятор), то в самом деле, можно пользоваться нормальной программой с первых секунд — все необходимые знания у 97% пользователей уже есть. Для более сложных задач (сложный редактор, система управления технологическим процессом, хитрая база данных, бухгалтерская, например) может потребоваться не только чтение инструкции, но и куры обучения на несколько месяцев. Потому что большинство людей просто не знакомы с решаемой задачей и даже польностью оптимизированный под эту задачу интерфейс им не поможет — они просто не знают, зачем он нужен.
Если задача тривиальная (простой калькулятор), то в самом деле, можно пользоваться нормальной программой с первых секунд — все необходимые знания у 97% пользователей уже есть. Для более сложных задач (сложный редактор, система управления технологическим процессом, хитрая база данных, бухгалтерская, например) может потребоваться не только чтение инструкции, но и куры обучения на несколько месяцев. Потому что большинство людей просто не знакомы с решаемой задачей и даже польностью оптимизированный под эту задачу интерфейс им не поможет — они просто не знают, зачем он нужен.
Обучение методике/принципам/etc, которые необходимы для использования продукта это отдельный продукт (будь то курсы или книга или ...), со своей целевой аудиторией, задачами и, иногда, жизненным циклом. И уж тем более это не readme файл, который Том призывает писать в самом начале проекта. Впрочем, его понять можно — он описывает все в контексте гитхаба, чтобы люди начали добавлять readme в свои проекты и тем самым привлекать новых людей в проекты (и гитхаб). Другое дело, что хак, а хаки имеют тенденцию накапливаться и бить по лбу своих создателей.
Автор статьи имел в виду примерно следующее — «выскажите вначале человеческим языком то, что хотите воплотить в коде».
Например, «Это будет библиотека для работы с графикой, она позволит быстро получить PNG-файл с изображением заданного размера. Изображение может включать прясоугольники, круги и фрагменты других изображений».
Всего пара строчек, а уже становится понятным, что, зачем, с какой функциональностью. Многие не парятся над тем, чтобы это записать, а потом ведь даже тестеру не отдать результат — тот просто не поймет, что за непонятный софт ему принесли и на что его проверять.
Например, «Это будет библиотека для работы с графикой, она позволит быстро получить PNG-файл с изображением заданного размера. Изображение может включать прясоугольники, круги и фрагменты других изображений».
Всего пара строчек, а уже становится понятным, что, зачем, с какой функциональностью. Многие не парятся над тем, чтобы это записать, а потом ведь даже тестеру не отдать результат — тот просто не поймет, что за непонятный софт ему принесли и на что его проверять.
Я обычно создаю файлик TODO
Человек описал типичный feature-файл из BDD или user-story из Scrum и назвал его «новой методологией». Обожаю, когда люди не изучившие важных аспектов «хаемых» систем начинают придумывать новые, решающие те же проблемы тем же путем :-D
То, что описывает Том, это не Scrum, т.к. бэклог с историями на реализацию, не хранится в репозитории кода, и не совсем BDD, т.к. менее детально — не определяет поведение методов в каждом случае, и понятно и команде разработчиков — кто, что и как собирается реализовывать, и пользователю — после окончания реализации кода Readme файл остается. Естественно, надо и к этой практике подходить с умом.
А вообще, agile методики, на то и agile методики, что не определяют обязательных правил, которыми надо руководствоваться: если вам это удобно и приносит пользу, используйте, если нет — не используйте. :)
А вообще, agile методики, на то и agile методики, что не определяют обязательных правил, которыми надо руководствоваться: если вам это удобно и приносит пользу, используйте, если нет — не используйте. :)
Бэклог с историями не храниться в репозитории кода
Почему? Что мешает юзер-стори хранить в коде???
не совсем BDD, т.к. менее детально — не определяет поведение методов в каждом случае
У Вас какая-то путаница в голове по поводу BDD. Есть 2 типа BDD — спецификационное и сценарное. Первое описывает поведение системы изнутри на примере объектных спецификаций, второе описывает поведение системы снаружи на примере поведенческих сценариев всей системы в целом. И я говорю про сценарный BDD, который подходит для реализации желаний Тома намного лучше нежели Readme файл:
github.com/knplabs/mink-demo/blob/master/features/search.feature
Почему? Что мешает юзер-стори хранить в коде???
не совсем BDD, т.к. менее детально — не определяет поведение методов в каждом случае
У Вас какая-то путаница в голове по поводу BDD. Есть 2 типа BDD — спецификационное и сценарное. Первое описывает поведение системы изнутри на примере объектных спецификаций, второе описывает поведение системы снаружи на примере поведенческих сценариев всей системы в целом. И я говорю про сценарный BDD, который подходит для реализации желаний Тома намного лучше нежели Readme файл:
github.com/knplabs/mink-demo/blob/master/features/search.feature
Как только появилась MS VS 2010, мы стали использовать TFS, который позволяет хранить UML диаграммы (вы не поверите, но мы их рисуем), User Story (да, да, именно они описывают хотелки пользователей с описанием ценности для бизнеса), Test Case (куда надо тыкать, чтобы убедится, что хотелка работает именно так, как ожидает пользователь), и… Ну да, у нас в TFS хранится и код, который привязан к диаграммам, хотелкам и Test Case. И при этом в SharePoint хранится куча Guidline, инструкций, документов. Ведь все упирается в размер проекта. Если у вас dll реализующая 2-3 функции, то и файл readMe при правильной разработке публичного интерфейса может оказаться лишним. А если вы разрабатываете систему на 10к+ пользователей, то может и то что я описал окажется мало.
Даешь методологию «Разработка основанная на About...»
Может вначале надо было бы определить, что должно войти в Readme файл, а потом уже призывать заменить им документацию? В процессе определения может выясниться, что это та же самая дока, только собранная в одном файле, и на самом деле мы имеем дело с таким себе спецификационным аналогом универсального метода «сделать все зашибись».
Как раз недавно видел код какого-то гема от Р.Бейтса, созданный по этой методологии. Она не исключает TDD, BDD и SCRUM, а только лишь улучшает их. Отличная методика. Спасибо, что довели это до русскоязычных программистов.
Смешная статья.
«Все эти TDD, BDD… не имеют смысла, а вот зато мой метод классно работает» — и дальше описывает ту же идею, что лежит в основе TDD и BDD: сначала подумать и описать, а потом уже кодировать. Идея сама по себе правильная, но такое претензионное начало настраивает читателей против автора и говорит о его неосведомлённости.
«Все эти TDD, BDD… не имеют смысла, а вот зато мой метод классно работает» — и дальше описывает ту же идею, что лежит в основе TDD и BDD: сначала подумать и описать, а потом уже кодировать. Идея сама по себе правильная, но такое претензионное начало настраивает читателей против автора и говорит о его неосведомлённости.
Этот README-файл, это же Vision & Scope Document.
В самом начале проекта действительно стоит чуть-чуть подумать в голове и на бумаге, поконцептуализировать. На данном этапе обратная связь может быть богаче от простого обсуждения, чем от кода.
Шаблон VSD от Karl Wiegers содержит ряд правильных вопросов, над которыми полезно подумать.
Но не увлекаться, конечно.
Кстати, возможны и другие формы размышления о концепции. Например, Personas или System Metaphor из XP.
В самом начале проекта действительно стоит чуть-чуть подумать в голове и на бумаге, поконцептуализировать. На данном этапе обратная связь может быть богаче от простого обсуждения, чем от кода.
Шаблон VSD от Karl Wiegers содержит ряд правильных вопросов, над которыми полезно подумать.
Но не увлекаться, конечно.
Кстати, возможны и другие формы размышления о концепции. Например, Personas или System Metaphor из XP.
Sign up to leave a comment.
Разработка основанная на Readme