Документирование кода или кто напишет документацию...

Код. Проекту не один год... Иерархия классов. На текущем участке работы — документации нет...

На первый взгляд, код очень простой, но разобраться довольно сложно, представление размытое ... очень сложно сконцентрироваться, просто теряю время, много... Если документация не будет сделана, кто-то другой тоже получит возможность опять потерять время. Совсем не хочется отвлекать других вопросами, но это — тоже вариант.

Года 2 назад на одном проекте мы искали виноватого, обвиняли всех — парня который делал архитектуру, а за спиной и менеджеров и заказчика... Только вот ничего не менялось!

А потом дошло... не один месяц прошел.

Не все могут в разумные сроки написать документацию — у них просто другие таланты...

Если есть парень, который сделал архитектуру, но затрудняется в доступно объяснить, научить как с этим работать, тогда кто-то другой должен взять эту инициативу на себя, нужно просто помочь, стать как бы посредником, хотя бы временно, иначе командный двигатель будет барахлить и будет плохо всем...

Это и есть командная работа, когда не обвиняют друг друга, а когда весело и приятно делать что-то вместе, когда механизм работает просто отлично! Просто сесть и сделать, не абсолютно все конечно, но то, что нужно, что позволит нормально работать.

Теми: документація

anonymous 20.09.2010 21:47

Прорекламирую и я свой инструмент для документации.Этот инструмент для средних и мелких проектов, связанных с разработкой ПО. Он не похож на инструменты уровня Enterprise. Однако в случаях, когда разработчики тесно работают с системой контроля версий SVN, может оказаться весьма полезным. Ориентирован в основном на тех, кто разрабатывает ПО для веб, но, возможно, будет полезен кому-то еще. Каждая разработка, если она хоть немного поэтичней, чем печать hello world, требует документации. И как-то так получалось, что я начинал писать документацию и все время наталкивался на то, что мне это неудобно: Документация в MS Word (Open Office) не имеет подсветки кода, держит все в одном длинном документе, его не положишь в систему контроля версий для отслеживания изменений. Такой документ невозможно без лишних трудностей сохранить в html-коде, который будет размещён на сайте. Microsoft HTML Help Compiler (и большинство програм для построения справки в формате CHM или WinHelp) позволяет все хранить в тексте, но не имеет подсветки синтаксиса, документ нельзя собрать в связанные html-страницы для выкладывания на сайт без active-x компонента Формат Docbook тоже близок к желаемому, но XSLT трансформации сложны, подсветка синтаксиса — хоть и решаемая, но проблема. Программы, генерирующие документацию на основе комментариев в коде (JDoc, PHPDocumentator) дают на выходе рабочий инструмент, но никак не документацию для конечного юзера. Чтобы обойти заявленные неудобства и была написана программа BullDoc. BullDoc — это система для создания документации. Представляет собой комплекс на php, который можно использовать без веб-сервера через командную строку, или в виде сайта под управлением apache. Исходники документации хранятся в текстовых файлах и могут быть помещены в svn. Документация экспортируется в полностью статический html (один файл на одну страницу или один монолитный файл), для размещения на сайте и для скачивания. Имеется экспорт в файл справки chm. http://www.bulldoc.ru

Відповісти

Підтримати

Думаю что всем будет полезно, недавно появилась полезная тулза, для документирования кода, пока что на ruby и только под linux:). Очень удобно из гуя на gtk+ и сразу если нада с форматированиями для RDoc.http://rubyforge.org/projects/.../

Постулаты: 1. Разработка не должна начинатся без технического задания описывающего все модули системы (или первый модуль и модуль взаимодействия между остальными модулями).2. Техническое задание на отдельный модуль обязано представлять полное описание логики работы модуля включая все интерфейсные элементы и поведение модуля при внешних ошибках.3. Весь код должен быть прокоментирован и отформатирован в едином формате.4. Документ созданый с помощью Doxygen (и UML диаграмма классов) не является документацией кода, а лишь коментируют его реализацию.5. Версионность технического задания должна совпадать с версионностью кода (тегов, бранчей в svn, cvs и т.д.) 6. При большом количестве програмистов код не должен содержать коментариев состояих исключительно из ссылки на номер тикета или раздела ТЗ. Кроме ссылки коментарий должен содержать развернутую информацию про изменения, reference на програмиста который их сделал и дату.При невыполнении любого из этих пунктов результат становится равным нулю и выброшенным на ветер деньгам.

Максим Кравцов Mac Developer в Kolo Global 20.09.2010 21:47

Мне очень сильно хотелось обратить Ваше внимание именно на коммандную работу, в частности, для документирования архитектуры, кода и т.д.

Идея организовать команду таким образом, чтобы люди сами проявляли инициативу в написании документации, и даже более того — писали ее друг за друга, помогали друг другу — я с таким еще не сталкивался (в первоначальном посте я не уловил этой мысли). Довольно интересный подход, хотя на первый взгляд несколько утопический.В мой практике каждый член команды пишет документацию на ту часть кода, за которую он ответственен, которую он разрабатывал. Пишет он ее от начала и до конца. И дело здесь не в размере команды (фирмы), в наложенном процессе разработки ПО, хорошем менеджменте или щедрых заказчиках. Это культура разработки — объясняем что это нужно, если не понимают или ленятся — заставляем писать.Но все равно наш подход несколько отличается от вашей идеи. В нашем случае документирование хоть и является частью процесса разработки, но это все-таки не командная работа. Нет такого, что кто-то написал вступление, что-то другой дополнил/исправил его, а кто-то третий написал основную часть.Возможно ваш подход может оказаться очень эффективным и удобным. И wiki может быть наиболее удобным инструментом для написания документации с таким подходом.Ну, а если работать по-старинке, то Doxygen + UML диаграммы — именно то что нужно.

Alexander Belchenko PM и ведущий разработчик в продуктовой компании 20.09.2010 21:47

окей. я дурак., но статья все равно — бред, и автор — больше не пеши.

Alexander Skakunov Founder в Місія на Марс 20.09.2010 21:47

2 bialix: когда не за что зацепиться, то коментов к посту 0−2. А Вадим Войтюк, кстати, прекрасно находит, за что зацепиться — и очень конструктивно критикует, респект; трудно представить, чтобы он написал «афтар, ты не умеешь писать. больше не пеши».

2Скакунов Александр: тут нечего критиковать. Не за что зацепиться. Согласен со всеми комментариями Vadim Voituk.

Это и есть командная работа, когда не обвиняют друг друга, а когда весело и приятно делать что-то вместе, когда механизм работает просто отлично!

А счастье это когда всё хорошо. Хорошо когда вокруг счастье. Надо быть счастливым, тогда будет хорошо. И чем лучше тем счатливей! Когда плохо это не хорошо, кого ни вини, так счастья не будет. Хорошо когда счастье.

2 bialix:, а мне нравится; как минимум хороший повод для обсуждения. И если уж критиковать, то лучше конструктивно, верно?

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

Спасибо за поправку, я действительно заблуждался в терминах. Что же касается того, что «кто-то» (как говорил автор заметки) должен взять на себя обязанности по документированию архитектуры — тут все зависит от конкретной ситуации. Описывать архитектуру проекта должен человек, который хорошо разбирается в ней. Не просто умеет хорошо писать код, а имеет достаточные знание о том, как работает каждый модуль системы. Т.е. этот «кто-то» играет важную роль в развитии проекта, и отвлечь его на документирование архитектуры довольно сложно. И если такой человек найдется, и будет выделено время для этой работы — это чистая удача. В большинстве же случаев этот «кто-то» — абстрактный человек.

Павел Подлипенский 20.09.2010 21:47

Согласен с Вадимом, архитектор, реализовавший черный коробок и не написавший ни слова, о том как он работает — диверсант в тылу команды;) Особенно, если проект долгосрочный и есть риск, что дописывать его будут уже совсем другие люди.

Vadim Voituk Principal Solutions Architect в Amazon Web Services 20.09.2010 21:47

Dmitry Zhariy: То что вы описали — это никак не самодокументированный код, а генерируемая документация. Что же такое самодокументированный код — почитайте в любой книге по Agile-методологиям (если не ошибаюсь понятие ввели ещё у К.Бэка) Тажке не путайте документирование кода и документирования архитектуры системы.Документирование кода (JavaDoc, PHPDoc, и тд) никто за программиста не сделает — тут с вами сложно не согласиться.Насколько понял, автор же предлагает делегировать документирование архитектуры системы отдельному сотруднику.

Код должен быть самодокументированным. По своему опыту, могу сказать, что само документирование кода — это наилучший вид документации, для того чтобы въехать, как «это все» (проект) работает. И при этом: 1. Документация по коду находится в одном файле с описываемым кодом: изменил код — сразу же можно изменить документацию (комментарии). 2. Когда я пишу комментарии для конкретного файла, я тем самым увеличиваю его полезный объем. А мне это делать не лень. 3. В зависимости от системы для парсинга самодокументированного кода, можно построить и иерархию классов автоматически. Doxygen такое может, например. Для С++ кода — это один из лучших вариантов. Есть языки со встроенной возможностью самодокументирования. В Perl — это POD-документация. 4. Написать пару строчек комментариев возле важной функции не составляет большого труда. При необходимости, эти пару строчек можно быстро найти (так как они находятся рядом с самой функцией) и, при необходимости, дополнить нужной информацией. 5. Парсеры самодокументированного кода могут преобразовать документацию HTML формат. HTML можно скомпилировать, к примеру, в CHM и — у нас готов API Reference с поиском и индексом. З.Ы.: Vadim Voituk: > Сама заметка и серии «записать пару мыслей, чтоб утром не забыть» — > IMHO ей не место в блоге DoU.А я думаю, что именно такой и должна быть заметка, чтобы ее тема могла бы быть развита в комментариях. Самое место ей на ДОУ (IMHO).

Sergii Voloshyn Product Manager в DOU.ua 20.09.2010 21:47

Вадим, я надеялся на то, что в комментариях основного блога будет больше умных мыслей.

Сергей, А чем blogs.developer.org.ua не угодил? + ещё в планету включить.

P.S. Сама заметка и серии «записать пару мыслей, чтоб утром не забыть» — IMHO ей не место в блоге DoU.

sorry, это пока нет форума.

IMHO метод «нанять писателя» — это значит снять с разработчиков ответственность за свою поделку и потакать их прихотям.Я предлагаю немного другой вариант решения проблемы: Хочешь в отпуск — пиши документацию по своим проектам. Пока не напишешь — заявление на отпуск не подписывается. Написал «лишь-бы было» — имеешь все шансы быть отозванным с отпуска.Аналогично с отгулами длительностью больше 3х дней.Если не можешь обьяснить свою архитектуру — это не архитектура, а просто поделки.Или же она необосновано сложна — делай проще и понятнее другим участникам проекта.Такой подход очень хорошо мотивирует сначала все продумать, потом согласовать с членами команды, а уже потом хвататься кодить реализацию или хотя-бы прототип.Побочным бенефитом является то, что знание об устройстве становится коллективным, а в таком случае критичность отсутствия документации смазывается. P.S. Сама заметка и серии «записать пару мыслей, чтоб утром не забыть» — IMHO ей не место в блоге DoU.

Если я правильно понял, то речь идет о документировании кода, архитектуры проекта и т.п. Как кто-то другой (кто не проектировал этот код, не реализовывал его) может описать как устроена архитектура, как реализован тот или иной алгоритм? Ведь человеку со-стороны просто придеться сидеть и разбираться с кодом. И он попадет именно в ту ситуацию, которая и была описана:

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

Еще я не согласен со следующим утверждением:

Не все могут в разумные сроки написать документацию — у них просто другие таланты...

Если не могут, то пусть учатся. Но скорее — не хотят. Тогда нужно заставить.И еще один момент — парень сделал архитектуру, но затрудняется объяснить как это работает или как с этим работать. Тогда «сделал архитектуру» — это слишком громко сказано. Он скорее всего просто написал код, к чему в основном программисты и стремяться. Для них, почему-то, писать документацию — это что-то низменное. Они хотят поскорее получить результат, чтобы что-то уже работало. А вот «сделать архитектуру» в моем понимании — это значит сперва задокументировать как это работает, а уж потом реализовать это в коде. Причем вот как раз при таком подходе первую и вторую часть работы могут выполнять совершенно разные люди.

Пост хорош тем, что мотивирует к действию. Так держать!

http://gettingreal.37signals.c...

Нанимайте хороших писателейЕсли вы задумываетесь над тем, какого рода специалиста можно еще пригласить на не занятое место, — наймите того, кто лучше других умеет вести документацию. Не важно кто он — дизайнер, программист, специалист по продажам или кто-то еще, его умение хорошо писать окупится с лихвой. Понятная, последовательная документация ведет к понятному и последовательному коду, дизайну, письмам, объявлениям и т. д.

Документирование кода или кто напишет документацию...

Схожі статті

Аудит і оцінювання. Вдосконалюємо процес тестування

Як створювати та оформлювати технічну документацію в IT: рекомендації для початківців і підказки для досвідчених

Навіщо дотримуватися документування на проєкті і хто це повинен контролювати

21 коментар

Підписатись на коментарі

Новини

Радимо почитати