Этот разработчик принимает документирование очень близко к сердцу.
Как он пишет код
все классы с описанием
Каждый класс, как public так и protected или private обязательно обладает описанием. В описание – несколько слов о назначении класса, имя автора, иногда ссылка на смежные классы, если необходимо – пометка «For internal use only».
все public методы с описанием
Каждый public метод или конструктор обладает описанием того, что этот метод делает, что он возвращает, какие параметры он принимает, какие на эти параметры накалываются ограничения и, иногда, что будет если параметр имеет тривиальное значение (вроде null или -1).
проверка параметров всех public методов
Каждый public метод или конструктор начинается с проверки входящих параметров. Проверяются условия объявленые в описании метода. Если хотя бы одно условие не выполнено, кидается exception.
сначала комментарии
Очень часто блок кода (или одна строчка) имеет комментарий, где человеческим языком объясняется, что сейчас будет происходить. Эти комментарии появляются до самого кода: сначала определяется сигнатура метода, потом пишется его описание, а потом – в теле метода – комментарии с примерным планом исполнения (что-то вроде: «Проверить параметры», «Подключиться к базе данных (здесь мы ещё не подключены)», «Исполнить такой-то запрос»).
названия классов, переменных и методов разумны
Эти названия подчиняются простому правилу: имя метода всегда начинается с глагола, имена классов и переменных никогда не содержат глагол. Ну, и конечно, названия классов, переменных и методов выбраны так, чтобы код легко читался даже без комментариев.
Как он коммитит в VCS
каждый коммит имеет комментарий
В каждом комментарии к каждому коммиту описание того, зачем были сделаны изменения. Почти никогда – что поменялось, но обязательно – зачем.
где возможно комментарий ссылается на номер баги
Если коммит исправляет какую-либо багу, то указывается номер это баги и её краткое описание (например: «Fixed bug 999 (put Cthulhu back to sleep)»).
Как он ведёт wiki
каждая подсистема обладает страничкой
Каждая разработанная подсистема имеет свою страницу. На этой странице – несколько слов про назначение подсистемы, если имеются, то ссылки на PRD (Product Request Document, тех. задание), несколько слов о реализации.
описание внешних интерфейсов
Если подсистема взаимодействует с внешним миром, то на страничке приводится описание открытых интерфейсов (иногда это просто ссылка на документацию кода, иногда – на WSDL, иногда просто пример сообщения). Написано это для того кто будет интегрироваться с подсистемой (хотя, на момент написание, этого человека может не существовать).
картинки
Очень часто описание содержит картинку. Это или UML-диаграмма, или два-три разноцветных квадратика, либо скриншот чего-то полезного. Картинки очень сильно облегчают понимание. Порой эффективнее нарисовать, чем написать.
каждое изменение страницы имеет комментарий
Комментарий объясняет зачем было сделано изменение.
Как он работает с bug-tracker'ом
комментарий баги при получении – ETA, сложность
Если бага не тривиальна, то при получении пишется комментарий в котором объясняется почему эта бага сложная и примерно сколько времени надо чтобы её пофиксить. В любом случае добавляется пометка, что бага «принята».
диалог с QA-инженером только через bug-tracker
Любые вопросы, комментарии, предложения – только через bug-tracker. Если что-то обсуждали устно (на встрече или за обедом), то тезисы обсуждения заносятся в bug-tracker. Диалог вроде: «А тут у нас, кажется, иногда отваливается левое крыло!», – «Так я это вчера пофиксил», заканчивается багой которая тут же закрывается.
как только бага пофикшена и фикс в закоммичен бага закрывается
Не откладывая до завтра, не сомневаясь, бага отмечается как исправленная.
при закрытии баги добавляется комментарий с объяснением для QA-инженера
Комментарий к пофикшеной баге содержит два-три слова про фикс и, иногда, подсказку для QA-инженера как этот фикс проще проверить и что стоит потестировать снова.
Как он отвечает на e-mail
время ответа на любой e-mail – не более дня
На каждый e-mail ответ пишется в тот же день. Если сразу ответить на поставленный вопрос невозможно, то следует объяснение почему и примерно когда ответ последует. Если письмо пришло не по адресу, то оно тут же переправляется.
e-mail адресован только тем, кому следует
Каждое отосланное письмо, будь то вопрос, комментарий, благодарность, предложение, адресован лишь тем людям кому его важно прочесть. К примеру, e-mail'у про изменение структуры какого-то класса в CC не добавляются CEO компании и девушка-секретарь.
в каждом e-mail'е – слова «спасибо» и «всего хорошего»
Каждый e-mail начинается со слов благодарности (за вопрос, комментарий, предложение) и заканчивается вежливыми словами прощания вроде «best regards», «have a nice day».
Однажды я спросил у этого чудака зачем он всё это делает. Он ответил, что у него ужасно плохая память на мелочи. Когда ему надо что-то вспомнить он заглядывает в код, CVS, buzill'у. Он ответил, что так проще QA-инженерам, потому что они могут смотреть на ход работы и писать полные планы тестирования. Он ответил, что так удобнее менеджерам, потому что они могут судить о сроках и о сложности подсистем. Он ответил, что другим разработчикам будет проще разобраться с его кодом. Он ответил, что другим разработчикам будет проще переиспользовать его код. Он ответил, что так учил Стив Макконнелл.
Я подумал: «ну не маньяк?». А как вы думаете, он – графоман или просто хороший разработчик?
