Так давайте же задокументируем это.

Проблема автоматической документации кода не пропадет до тех пор, пока сам язык не будет предусматривать готовых конструкций для реализации документации или же не появится единый и всемогущий стандарт, который все примут как единственно верный и будут следовать ему, заглядывая в рот, всегда, везде и во веки веков. Говоря другими словами, проблема исчезнет не очень скоро =). Но хорошие подвижки в этом направлении есть. В основном, они заключаются в появлении мощных средств автоматизации документирования кода, нежели каких-то семантических изысканиях, но и это уже хорошо. Осталась мелочь - воспитать сознательных разработчиков =). Но это не задача технических писателей, которые оказываются крайними в данной ситуации и которым только и остается жаловаться на своих коллег-программистов: «Вот, дескать, какие нерадивые, не заставить их толком что-нибудь черкнуть по теме». Это прямая обязанность PM проявить свою волю, характер, новый лакированный кнут, наконец, и добиться от кодеров не только стройного кода, но и скупого и сумбурного слова. Выражаться это может в чем угодно: в изменении штатного расписания, премиях и выговорах, приклеивании на лоб стикера с цитатами из «соглашения о кодировании», запретом в качестве наказания использовать в своих программах переменную i сроком на год и т.д. Это что качается организации работы. Ну а с технической точки зрения, если оценивать текущее положение дел по сравнению с тем, как это было лет …надцать назад, когда для создания небольшого HLP файла нужно было пролить ведро пота и слез, не говоря уже про какую-то там синхронизацию документации и кода, то у меня на губах невольно появляется улыбка. Сквозь пелену небытия я вижу светлое будущее, в котором профессия программиста последует в легенду, прямиком за профессией трубочиста. А я буду разводить пчел в деревне далеко от этой суетливой жизни и вспоминать эти дни с легкой грустью в области поясницы. Ну да ладно. Довольно иронии, поговорим более конкретно о документации.

Само по себе документирование кода – процесс непрерывный, который не останавливается ни на минуту, пока изменяется код и дышит программист =). Может быть, это звучит чересчур пафосоно, но дело обстоит так, что код и документация к нему – слишком связанные между собой вещи, чтобы можно было бы себе позволить работать с ними по отдельности. И если в прикладных программах зачастую встречается некий временной лаг в выпуске документации, который пытаются заполнить юзенетом и форумами поддржки, то для разного рода SDK, API, IOS-ов и систем с частыми и критическими обновлениями отсутствие или ляпы в документации могут стоить хороших денег.

Как и любая серьезная среда разработки, Delphi, помимо обычных комментариев, давно имеет встроенное средство автоматизированного документирования кода. Если быть точным, то их целых два! Разных. В первом случае можно поставить галочку «Generate XML Documentation» в опциях проекта, и помимо откомпилированных файлов мы получим ещё несколько XML файлов с документацией! Дальше можно делать с ними все, что заблагорассудится. Вот так вот по-спартанcки просто и красиво. Примечания, которые попадут в документацию, должны содержать три знака «деления» (по научному, три слэша ) и идти перед идентификатором. Но к сожалению, баги, как всегда, портят всю малину. Уже года два как Borland спешит исправить их в прекрасном встроенном средстве документирования кода, так что пользоваться внутренней генерилкой многим пока что-то неохота. Подробнее о проблемах можете почитать у коллеги

Второй способ предоставляет нам Тогезер. Это более мощное и тяжеловесное решение. О нем я уже упоминал в своих «сентенциях». Документация на выходе получается шибко навороченная, с диаграммами классов, деревьями и закладками. Проблема одна: хрупкость конструкции «модель – код», которую очень легко привести в нерабочее состояние шаловливыми ручонками, после чего модель и код живут сами по себе, а процедура синхронизации между ними способна уничтожить и то, и другое.

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

Pasdoc – калька Javadoc для Паскаля. Для тех, кто привык к Javadoc – это пожалуй, самое подходящее решение. Только мы же пишем на Паскале, поэтому хотелось бы воспользоваться теми особенностями, которые он предоставляет, а именно – разделение интефейса и реализации. Многие современные языки избавлены от этой заскорузлой традиции, берущей свои корни где-то в глубинах середины прошлого века. Встретить такой дотошный подход можно, пожалуй, что только в родственниках Паскаля – Модуле, Аде, PL/SQL и т.д. Основным неудобством здесь является дублирование информации, т.е. двойное описание процедур и методов, если они должны быть видны вне этого модуля. Поменял что-то в реализации - изволь править в интерфейсной секции и наоборот.

Многие «паскалисты» уже не помнят, что процедуры, функции и методы в Implementation – секции можно не описывать подробно. Достаточно указать название, но можно опустить все параметры и даже тип возвращаемого значения функции. Например, такой модуль замечательно откомпилируется, но жутко режет глаз (не только потому, что его тяжело отформатировать в этом блоге):

unit Unit1;

interface

uses
Windows, Messages, SysUtils, Variants, Classes, Graphics, Controls, Forms, Dialogs, StdCtrls;

type
TForm1 = class(TForm)
Button1: TButton;
procedure Button1Click(Sender: TObject);
private
public
procedure MyTest(Num3: Integer);
end;

procedure Test(Num1: Integer);
function isTest(Num2: Integer): Boolean ;

var
Form1: TForm1;

implementation

{$R *.dfm}

function isTest;
begin
Result := Odd(Num2);
end;

procedure Test;
begin
Sleep(Num1);
end;

procedure TForm1.Button1Click;
begin
MyTest(1000);
end;

procedure TForm1.MyTest;
begin
Test(Num3);
isTest(Num3)
end;

end.

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

Раньше, когда в возможности редакторов входили только функции перевода каретки, двойная работа особенно тревожила начинающих программистов-максималистов, которые острее всего чувствуют, как плохо устроен этот мир. Сейчас, слава богу, появились технологии, которые позволяют синхронизировать код интерфейса и реализации практически бескровно, поэтому преимущества разделения выходят на первый план. Полистайте-ка описание какого-нибудь класса с десятью – пятнадцатью методами в той же Яве, да ещё с подробным описанием для Javadoc и сравните с объявлением в Delphi. Вы будете приятно удивлены конкретностью и лаконичностью последнего, помещающегося всего на одной страничке. Так вот, возвращаясь к Pasdoc, хотелось бы, чтобы в сей замечательной программе была предусмотрена возможность хранить комментарии и в теле методов. Во-первых, это добавило бы компактности интерфейсной части кода. А во вторых, решило бы проблемы разного рода генераторов и автоформаттеров кода, после работы которых комментарии начинают гулять по модулю, потеряв всякую привязанность к своим прародителям. В остальном, Pasdoc – готовое решение для создания неплохой документации.

Более дельфовым можно считать другой Opensource проект: DelphiCodeToDoc. Развивается он медленно, но верно, и за 4 года достиг версии 0.20 Beta! Смех смехом, но эта разработка умеет понимать комментарии в секции реализации и использует синтаксис JavaDoc. Кто привык к Inline комментариям, может воспользоваться ими. В целом, неплохая альтернатива PasDoc.

Небольшая, но платная программа Pascal Browser тоже может создать HTML документацию по вашему проекту. Штука предельно простая, комментарии берет как из интерфейсной части, так и из реализации. Основным её преимуществом, по-видимому, является то, что ключевым в названии Pascal Browser является слово Pascal. Следовательно, она для Паскаля самое что ни на есть родное решение. Не знаю, можно ли её рекомендовать для серьезных разработок, потому что никогда ей всерьез не пользовался. =) Но работает. По крайней мере, в песочнице.

Doc-o-matic. Посмотрев на это чудо, понимаешь, что будущее если не здесь, то уже где-то совсем близко. По крайней мере, я до этого не много встречал настолько демократичных и удобных программ по работе с исходными кодами. Ей совсем не важно наличие хитрых управляющих конструкций из загадочных звездочек, крышечек, закорючек, собачек и всего подобного перлового антуража, который приводит обычных людей если не в бешенство, то в легкий ступор. Если ваш исходный код имеет комментарии, и эти комментарии в нем расположены перед идентификаторами, то можете считать, что половина работы уже сделана. Надеюсь, что великий эстет в вас уже благополучно помер, поэтому останется только немного причесать внешний вид получаемого файла, добавив чуточку форматирования. Благо, оно практически не отражается на исходных комментариях, поскольку реализовано с помощью интуитивно понятных тегов. Результирующий хелп может быть представлен в различных форматах, среди которых обычный HTML, CHM, XML, PDF и старый добрый HLP. А как реализован QA менеджер для поиска недокументированных частей проекта! Это просто песня! (Похожую идею я наблюдал в SequoiaView шесть лет назад. И надо признаться, даже сейчас ей периодически пользуюсь, когда надо найти нечто большое, засирающее диск.)
Нельзя сказать, чтобы в Doc-o-matic не было глюков, но где их нет? Периодически всплывают проблемы с блуждающими комментариями, когда из-за редактирования исходного кода случается, что программа принимает описание одного идентификатора за другой. Есть закавыка с конкурентными изменениями исходного кода из Doc-o-matic и из другой программы. В этом случае программа не дает сохранить добавленные комментарии в код, ссылаясь на то, что код был изменен и требует ресинхронизировать файлы. В принципе, понятно и разумно, но очень неудобно. Самый же главный недостаток Doc-o-matic – это его цена. Правда, недавно вышла урезанная бесплатная версия – для личных нужд. Ну а целом, Doc-o-matic - решение зрелое и удобное. Джедаисты опять же давненько юзают. В общем, как говорится – «Выбор редакции» =).
В заключении хотелось бы отметить, что есть множество и других систем, неплохо зарекомендовавших себя в этом нелегком деле – документировании кода. Стоило бы, пожалуй, упомянуть и RoboDoc и XHelpGen из KOL. Но конечный выбор стоит всегда за командой разработчиков со своими традициями, наработками и решениями. Что-либо советовать в этом деле я считаю неуместным, так как наличие собственной головы приносит неоценимую пользу в жизни. Правда, не всем. И ещё грустно сознавать, что декларативные заявления небезызвестных компаний о том, что та или иная фича реализована в её продукте ещё не значат, что эта фича работает как надо. И это не касается только CodeGear. Это явление повсеместно. Помните, как в том анекдоте:
Секретарша шефу по мобильному:
- Вы по пути в офис? Осторожнее, по радио передали, что какой-то придурок едет по встречной полосе!
- Да он тут не один! Их тут ТЫСЯЧИ!
Пока в руках не повертишь, не поймешь – действительно ли дело обстоит так, как написано в глянцевом пресс-релизе. Наличие же стороннего ПО, аналогичного по функциональности, может быть сигналом: "Что-то не так в консерватории". Ведь, как известно, свято место пусто не бывает…