Блог веб-студии RubyRuby

Здесь мы делимся нашим опытом.

Документирование проектов

Вопрос:

Вы работаете с тысячами клиентов в таких сервисах как Basecamp, Highrise и других. В них реализовано множество продвинутых и сложных функций, но тем не менее, как вы документируете свои проекты ? Насколько легко недавно нанятому разработчику разобраться как ваши продукты работают ?

Отвечает David Hansson:

Можем прямо сказать, что мы не документируем наши проекты. По крайнее мере не в традиционном понимании когда пишется целый том, который существует отдельно от кода, и который нужно прочитать новичку. Я никогда не видел чтобы этот подход работал целостно и успешно во всех софтверных компаниях с которым у меня было сотрудничество.

Более того, я не нахожу необходимости в документации для той работы что мы делаем. Наш крупнейший продукт, Basecamp, содержит более 10 000 строк кода. В действительности, это не так уж и много. Для разработки всего мы обычно используем Ruby on Rails, это означает что большинство Rails программистов будут знать примерную схему нашего приложения с самого начала. Это теже самые соглашения и паттерны используемые повсюду.

Мы пытаемся честно делать свою работу поддерживая тестовые сценарии актуальными и исчерпывающими. Basecamp имеет соотношение кода к тестовому коду 1 к 1.2 (спасибо настойчивости Ямиса), у Highrise это соотношение 1 к 0.8 (плохой я). Поэтому мы можем менять код нашего проекта и чувствовать себя достаточно комфортно, по крайней мере мы не убьём целый приложение, сделав ошибку, которую обнаружит тест.

В заключении, мы пишем наше приложение в восхитительно выразительном и кратком языке программирования Ruby, что приводит само по себе к стилю программирования который проповедует Кент Бэк в книге Smalltalk Best Practice Patterns. Держите свои методы короткими и выразительными. В среднем, наши модели содержат 4 длинных строчки. Добавление документации к методу делает в том случае, когда реализуется определённое неочевидное решение, котороре нельзя переписать в более простую форму.

Написание документации для вашего кода – это очень тяжелый, прямолинейный, распланированный вариант создания вещей. Может быть, это то, что вам нужно когда ваша среда содержит множество деталей или у вас есть множество сложных правил которые нужно реализовать. Но если вы не обременены подобными вещами, я рекомендую вам поработать над качеством вашего кода самого по себе и смотреть сможете ли вы обойтись без конфликтов непонимания кода с новыми разработчиками.

Оригинал статьи вы можете найти здесь http://37signals.com/svn/posts/838-ask-37signals-how-do-you-document-code

Заказать сайт на Ruby on Rails

Комментарии