Вчера на одном дыхании прочел книгу под названием «RTFM» (она на русском, всего 100 страниц). Очень рекомендую прочитать. Книга о том, как правильно строить сервисный бизнес.
Сказано в книге все правильно и умно, но я бы сказал, слегка упрощенно. Упрощенно в смысле, что автор дает правильный метод работы, но абсолютно опускает проблемы, которые возникают даже при правильном методе работы.
Тем не менее, еще раз рекомендую прочитать книгу. Кстати, а вот и блог автора — блог.
Второе, хочу дать ссылочку на статью (теперь уж на английском) — Avoiding Development Disasters. Очень точно описываются почему большие и слишком хорошо финансированные проекты чаще всего заканчиваются полным крахом.
И третья, мысль, которая вышла из вчерашнего спора с другом. Очень многие (особенно хорошие) разработчики говорят, что код должен является единственной и главной документацией (самоописывающий код). Что если нужно создавать отдельную документацию — это плохо, так как появляется второе «отображение» кода, которое может не обновляться и устаревать и расходится с кодом, что только усложняет понимание.
Я с этим категорически не согласен. Только небольшой проект очень хорошего написанного и прокомментированного кода можно понять без дополнительной документации. Когда же у вас на руках проект с миллионом строк кода, то для того, чтобы понять что и где происходит зачастую нужно будет проглядеть пол проекта (прилагая много усилий по удержанию в голове того, что вы еще видели и ни с чем не связали). При этом простая диаграмка, показывающая разбиение на модули и помудульная диаграмка, которая показывается основные взаимодействия внутри модуля может сохранить дни (если не недели), на том, чтобы понять, как проект работает.
О… Пока писал, еще одна мысль всплыла. Опять же, у программистов зачастую есть проблема ownership’а. То есть, они чувствуют, что владеют/отвечают за какой-то кусок работы. И постепенно в этом куске работы, они начинают делать все так, чтобы ИМ было удобно (не думаю о остальных, учитывая что они сами работают над этим участком). Мысль, которую я некоторое время назад сформулировал — владеть нужно проблемой и за нее отвечать, а код должен таки оставаться общий. Именно поэтому код должен комментироваться, документироваться и придерживаться другими методами доступным для остальных разработчиков.
По поводу мысли №3 есть замечательная байка — http://gaperton.livejournal.com/32772.html
Притча конечно хороша. Я только два кусочка хочу оттуда процетировать:
Как-то __года через три__ ко мне подошел коллега, с вопросом.
Второй важный аспект этой философии — понимание того, что __код пишется в первую очередь для человека__.
Итого, мы имеем что товарищ за три года «прочел» код системы и стал его понимать. При этом судя по всем первый год он просто просрал нисделав током ничего… Ну, что же… Если для компании финансово выгодно вкладываться в 3 года работы нового сотрудника, то удачи им и попутного ветра. (Сейчас по индурстии среднее время работы в компании 3-4 года. )
Второе, это то, что код должен быть ориентирован на человека. Опять же этот самый Tal Korin вероятнее всего достаточно активно дрючил там тех, кто писал код, который не предназначался для понимания. И соотвественно если он это делал 10 лет, то проект был хоть большой, но разумный. Что будем делать, если проект писался вовсе не Tal Korin’ом, а десятью Васями Пупкиными?
Главное не прочитать код большой системы, а понять принципы на которых эта система строилась. А понять это можно только из кода. И только код нужен для решения проблемы — состояние документации никак не влияет на степень решения проблемы. Поэтому код — это альфа и омега для разработчика.
Для больших систем период первичного обучения вполне может составлять несколько месяцев. Я например в первые несколько месяцев тоже разбирался в принципах построения системы — попутно фиксая мелкие баги в различных подсистемах. Хотя мне было проще — основной язык Python, да и опыта у меня на тот момент было больше.
А если проект делался десятью Васями Пупкиными — и его надо поддерживать — закладываем в бюджет рефакторинг, потому что это будет дешевле.
>Главное не прочитать код большой системы, а понять принципы на которых эта система строилась.
согласен.
> А понять это можно только из кода.
не согласен.
Есть три сразу приходящих на ум метода
а) Получить устно информацию от того, кто ее знает. (Для этого нужен человек который знает)
б) Прочесть информацию в виде актуальной документации. (Для этого нужна актуальная документация)
в) Прочесть и разобраться в коде.
Код хорош только тем, что он всегда есть и его не может не быть.
Следующий вопрос состоит в том, насколько дорого иметь а), поддерживать б) или читать в).
У каждого из этих пунктов есть цена.
>Для больших систем период первичного обучения вполне может составлять несколько месяцев.
Я думаю несколько месяцев — достаточно оптимистичная оценка. В той статье приведен классический пример, когда человек спутил 7 месяцев работы в топку.
>А если проект делался десятью Васями Пупкиными – и его надо поддерживать – закладываем в >бюджет рефакторинг, потому что это будет дешевле.
Дешевле чем что?
Вопрос, что если код написан десятью Васями, то чтение кода и понимаение архитектуры из кода будет гораздо более длительным процессом.
Для того, чтобы делать рефакторинг нужно сначала понимать архитектуру, чтобы отрефакторить что-то плохое в что-то хорошое.
Дело в том, что цена навыка чтения кода входит в цену разработчика — в отличие от остальных пунктов.
Насколько я понял из статьи http://gaperton.livejournal.com/32772.html и комментариев к ней, человек несколько месяцев ждал командировки.
Рефакторинг будет дешевле чем поддержка говнокода + поддержка документации к этому коду в актуальном состоянии. Не факт что использовалось оптимальное архитектурное решение и что архитектура не будет меняться. А для ревью и оценки необходимо и достаточно высокоуровневых требований — задач которые должна решать система — которые уже можно сравнивать с задачами которые система решает фактически (а это можно узнать только из кода).
>Дело в том, что цена навыка чтения кода входит в цену разработчика – в >отличие от остальных пунктов.
И?
>Рефакторинг будет дешевле чем поддержка говнокода + поддержка >документации к этому коду в актуальном состоянии.
М… В целом согласен. Но есть все таки проблема яица и курицы.
Чтобы разумно делать рефакторинг — систему таки надо понимать.
> И?
Разработчик бюджетируется без вопросов. Поддержка документации к коду — уже может встретить сопротивление. Лишний человек — еще больше возражений.
> М… В целом согласен. Но есть все таки проблема яица и курицы.
Документация к коду однозначно вторична по отношению к коду. В отличие от высокоуровневых требований, производным от которых и есть код.
> Чтобы разумно делать рефакторинг – систему таки надо понимать.
Для больших систем — надо понимать задачи.
>Разработчик бюджетируется без вопросов. Поддержка документации к >коду – уже может встретить сопротивление. Лишний человек – еще >больше возражений.
Ну, легкость бюджетирования, хотя и очень важный, но все таки не единственный пункт.
Вот, бюджет на чай для сотрудников можно выбить легко. Вопрос заключается в том, насколько от этого повысится производительность.
По поводу пункта номер 3:
Я предлагаю не смешивать две вещи: комментарии в коде и артефакты описывающие архитектуру системы.
Артефакты описывающие архитектуру системы нужны, особенно если проект развивается и приходят новые люди. Данная вещь очень способствует пониманию принципов работы системы и значительно ускоряет процесс вхождения. Кстати, возможно разработчики не хотят чтобы другие люди тоже участвовали в проекте потому и не хотят описывать подобные штуки 😉
А вот комментарии в коде спорная штука, по моему мнению пользы от них немного. Лучше писать код так чтобы его можно было читать как комментарий. Я вот например никогда не верю комментариям в исходном коде, люди ведь ошибаются и ленятся. А код идеальная штука для документирования поведения.
В итоге я хочу сказать что порой написание комментариев превращается в карго культ подражателей и это есть великое зло. Люди ведь с неохотой занимаются глупыми вещами.
Боюсь, что люди не путают. Они именно протев артефактов описывающих систему.
Как и документация может быть полезной и нет, так и комментарии.
Естестевенно бывают дурацкие комментари а-ля
// Проверяем на ноль
if (index == 0)
С другой стороны, если для понимания какого-то куска кода, нужно перелопатить много документации/другого кода, то вполне для ускорения процесса, можно и комментарии вставить.
Как пример, сейчас вожусь с драйверами. И там где-нибудь в средине длинной функции, что-нибудь в ввиде
if (IRP->StatusFlag & IO_NOCACHE)
{
… // какая-то специальная обработка.
}
Для человека было абсолютно актуально что это за случай, для меня — второй день копаюсь в инете и по книжкам. Особенно весело, что крешится именно в этом самом кусочке, так что понять его прийдется.
P.S. Если сравнить затраты которые нужно было сделать человеку, чтобы описать этот специальный случай ( 20 секунд) и время, чтобы мне в нем разобраться (ну пусть скажем 4 дня выйдет), то комментарий явно вышел бы полезный.
Раз не хотят, то значит есть причина. Может быть они сами не понимают что пишут или затраты на делание такой документации высоки.
А по поводу случая: откуда же человек мог предполагать что падать будет именно в этом месте 🙂 Я конечно утрирую, но нельзя ведь прокомментировать все спорные случаи. Да и что непонятно для одного, тривиально для другого.
Но опять же, насколько я понял, идет работа с каким то api. А вот интерфейсы внешнего api надо всегда документировать. Огнем и мечем надо жечь это правило.
>Раз не хотят, то значит есть причина. Может быть они сами не понимают что пишут или >затраты на делание такой документации высоки.
Честно говоря меня эта идея удивляет о высоких затратах на комментирование (надо будет отдельно маленькую статейку написать).
Например потратить 3 дня на один баг (даже не слишком важный) считается вполне нормально.
Если потратитьо те же 3 дня на написание комментариев. То можно легко прокомментировать (имеются в виду полезные комментарии) гигантское количество знакомого кода.
Я скорее склоняюсь к другой теории. Не пишут комментарии, потому что сам человек от этого не получает выгоды. КОгда работаешь над кодом — сам его знаешь, а о других не думают (специально или не специально, уже второй вопрос).
Насчет того конкретного случая, который я описал — это так просто в виде примера.
>Что если нужно создавать отдельную документацию – это плохо, так как появляется второе “отображение” кода, которое может не обновляться и устаревать и расходится с кодом, что только усложняет понимание
Мне кажется, что те, кто так говорят, ставят проект с ног на голову.
Не документация должна быть отображением кода, а код — отображением документации (спецификации). Ведь код играет подчиненную, а не управляющую роль
А мне кажется что те кто говорит: «Не документация должна быть отображением кода, а код – отображением документации (спецификации)», редкостные бюрократы 🙂 Ведь в спецификации нормально не опишешь большинство вещей (или это может занять слишком много времени).
Я нисколько не против спецификаций, но ведь главная цель это решить проблему пользователя? Или я заблуждаюсь? 🙂
Истины тут нет, все зависит от команды и ряда других вещей. Иногда писать код без спецификаций самоубийство, а иногда они только вредят делу (даже в больших проектах).
Я бы сказал, что высокоуровневые требования достаточно редко вредят делу. Но, я согласен, что детальный список всех всех требований, поддерживаемый в полном порядке — очень дорогая вещь, которая вероятнее всего не окупится.
Что-то waterfallom смердит
М… Это уже достаточно сложный вопрос. При программировании софта для космических аппаратов — согласен 100% (первична спецификация, вторична реализация), для программирования быстро меняющегося и устаревающего софта — не совсем согласен (высокоуровневые требования важных, полное документривароние всех требований нереально).
Почему всегда приводят в пример космические аппараты? Что, у всех такой большой опыт программирования космических аппаратов? 🙂
Потому, что одна маленькая ошибочка в софте может привести к просиранию многих миллиардов долларов.
http://en.wikipedia.org/wiki/List_of_software_bugs#Space_exploration
А насчет личного опыта. Основываясь на него тяжело что-то объяснить. Гигантское количество программистов ничего сложнее чем …. м скажем форум на PHP не писали.
Про документацию я как-то писал. Если цель в том, чтобы не дать демону сложности пожрать ваш проект, то кода, сколь угодно самодокументирующегося решительно недостаточно. Нужны еще как минимум логи багтрекера, протоколы митингов и регулярные design review.
Спасибо 🙂 Статья понравилась. Нормальный взвешенный подход с объяснениями, для чего и что нужно.