Документация - конечно - полезное дело.
Но не в таком виде:
QFont::QFont ( const QFont & font )
Constructs a font that is a copy of font.
- это простите - "масло масляное".
Что реально важно в документации, так это секции типа Discussion, Remarks, ReturnValue или описание "граничных условий".
С документацией для "проектно-зависимых" (а не "коммерческих") библиотек - есть проблемы:
1. Такие библиотеки гораздо чаще меняются.
2. Далеко не все разработчики способны описать принципы работы "на человеческом языке" (это - данность - я сам - такой). Соответственно - нужен "технический писатель". С которым разработчика ещё нужно "как-то договариваться".
3. "Коммерческие" библиотеки не так подвержены "волюнтаризму требований". У "коммерческих" библиотек - СВОИ внешние авторы. Если требования не ложатся в архитектуру коммерческих библиотек - эти требования априори не выполнимы, если конечно ВНЕШНИЕ авторы не согласятся менять архитектуру под "хотелки" конкретных пользователей.
Документация часто не даёт "контекст" использования.
Контекст использования (и примеры) - хорошо дают ТЕСТЫ.
Текстовая документация далеко не всегда показывает СВЯЗИ между проектными классами.
/дабы не безмолвствовать/
ОтветитьУдалитьСогласен со всеми пунктами.
Жалко, что не все это понимают. И такое непонимание приводит к таким случаям, когда метод называется так, а делает он нечто другое.. и потом естественно утверждают, что описание вида
> Constructs a font that is a copy of font
очень полезно и необходимо...
:-)
Удалить>Документация - конечно - полезное дело.
ОтветитьУдалить>Но не в таком виде:
Вы так говорите, будто это описание затрудняет понимание. Между тем хоть какое-то описание в этой документации есть у любого метода, и это несомненно - плюс. "Лучше безобразно, но однообразно."
>Текстовая документация далеко не всегда показывает СВЯЗИ между проектными классами.
Связи между классами это вообще основа документации.
"Вы так говорите, будто это описание затрудняет понимание."
Удалить-- не затрудняет, но это - ТРАТА ВРЕМЕНИ, которого и так - КРАЙНЕ НЕМНОГО.
Ну это - моё мнение.
"Лучше безобразно, но однообразно."
Удалить-- тут - сложно не согласится, я сам так считаю. Но не стоит ничего доводить до "абсолюта" (ИМХО). Да и времени - жалко.
>Такие библиотеки гораздо чаще меняются.
ОтветитьУдалитьВ дополнении документации нет ничего страшного, а существующие функции менятся не должны вообще.
>Далеко не все разработчики способны описать принципы работы "на человеческом языке"
Подобного рода текст любой программист в состоянии написать.
"Подобного рода текст любой программист в состоянии написать."
УдалитьЕсть некоторые анонимы, которые своим тоном не очень располагают к общению. Простите уж.
Но я всё же отвечу.
Я САМ написал много фреймворков и библиотек.
И я их "продавал" коллегам с тем или иным переменным успехом. Что-то продал, что-то нет.
Но по-любому - качеством "продажи" (и документации - я недоволен). Может быть коллеги - откомментируют это (если захотят).
Я пробовал и xHelpGen и Doc'o'Matic. И много чего ещё.
Проблема - НЕ в инструментах.
Проблема - В ЯЗЫКЕ и СПОСОБЕ донесения.
Так что - можете считать меня дебилом :-)
UML оказался не "серебряной пулей" и не "окончательным решением", но он - ПОКА - наиболее удачен.
Только и всего.
Хотя - опять же - может быть меня коллеги поправят. Если захотят. Ну или сочтут нужным.
"а существующие функции менятся не должны вообще."
УдалитьПростите, но это мне - СМЕШНО. Наверное я чего-то не понимаю.
Вам правда удаётся такое?
"Подобного рода текст любой программист в состоянии написать."
Удалить-- мне кажется, что вы просто судите по себе :-) А в мире есть и такие как я :-)
Можно вопрос?
Вы САМИ много кода написали? Задокументировали? "Продали"?
Это не попытка "фаллометрии". Это мне ПРОСТО НЕИНТЕРЕСНО.
Просто мне хочется знать "метрики" и ГДЕ Я ОШИБАЮСЬ.
>UML оказался не "серебряной пулей" и не "окончательным решением", но он - ПОКА - наиболее удачен.
УдалитьUML не замена документации, и необходимость документирования не отменяет.
>Простите, но это мне - СМЕШНО. Наверное я чего-то не понимаю.
>Вам правда удаётся такое?
Конечно, это же один из базовых принципов. По другому - никак.
>Можно вопрос? Вы САМИ много кода написали?
Достаточно.
> "Лучше безобразно, но однообразно."
ОтветитьУдалитьМеня всегда передёргивает от этого выражения. Лучше однообразно и не безобразно. Безобразно лучше вообще не делать. ИМХО )
> существующие функции менятся не должны вообще
Это очень походит на принцип write only при кодировании. Далеко с таким принципом не уедешь.
>Это очень походит на принцип write only при кодировании. >Далеко с таким принципом не уедешь.
ОтветитьУдалитьпод write only кодом обычно понимают нечитаемый код. Здесь совсем другой случай. Нельзя ломать API, вот и всё. И ничего нового здесь нет - это базовый принцип.
> Нельзя ломать API
Удалитьмне показалось, что речь о коде. Если про API (сигнатура вызова и ожидаемый результат) - то конечно, лучше ничего не менять (ну с оговорками об области видимости этого API).
Будет "многобукв", джентельмены, но без "предварительного застирывания" не получается.
ОтветитьУдалитьПостановка вопроса - "зачем такая документация". Ответ простой. Ничего не бывает немотивированным способом. Если нет рациональности в поступках/деятельности, то это потому, что вы её не видите. Это не оскорбление, это - факт. Я даже готов слегка пожертвовать имиджем Embarcadero, т.к. компания для меня не идол, а средство быть в IT.
Если вы что-то "продаёте", то очень часто ФАКТ НАЛИЧИЯ фичи важнее, чем её полезность. Начиная от тупого 80/20 и заканчивая правилом "трёх сигма", нормальным законом распределения, сложностью (ли) человеческой психики, "правилом золотой рыбки" и пр. пр. пр.
Отсюда проистекает: "безобразно и однообразно". Представьте, что вы даёте пользователю что-то c API(наплевать что, пусть "пульт от телевизора"), где есть сложные кнопки, а есть простые. Ну ка в инструкции (=документации) вы опишите 5 сложных кнопок, а 10 простых просто "забудете".
Что мы получим на выходе? Большое пользовательское "спасибо" и вечный троллинг на тему "они даже доки писать не могут, куда им пульты делать! а уже про телевизоры вообще молчим")
Сейчас немного "грязи".
ОтветитьУдалитьКак когда-то Николай Зверев меня обозвал "нерукопожатным", так этим имиджем и пользуюсь.
Проблема в том, что интеллект никак не помогает анализировать. Большинство жизненных задач очень тривиальны (в плане аналитики). Сначала я верил в программистов - но после Embarcadero и ряда насыщенных и кровавых тролль-битв несколько сменил точку зрения. Программисты, будучи высокими интеллектуалами, также легко попадаются на удочку "личностного восприятия". И не могут думать объективно. Мысленно себя надо поставить "над" (хотите? "вне") системы. Сейчас будет цепочка.
Сева (можно уже на ты, да?), я тебя никогда никак не называл и уж тем более, не обзывал.
УдалитьЯ очень уважаю твой труд, и если чем-то случайно обидел - извини.
Каждый раз, когда мне программист говорит "зачем?" мне хочется взять его за шиворот и... головой в монитор. Брат, ты бинарное дерево с обходом может по памяти написать, причем даже без не то, что отладки - проверки синтаксиса. Или 4-нарный JOIN написать. Про ассемблер вообще молчу. Давайте на данном примере включим лучшие отдела нашего мозга и не будем говорить "зачем".
ОтветитьУдалить1. Документация в классической инженерии служит для того, чтобы можно было ИЗГОТОВИТЬ что-то. Пусть это будет болт М6. Чертеж? Да. Доп. документация. Технология. А потом по этой документации сделали деталь. Не? Ок, поправили документацию и ок.
2. Отсюда в ИНЖЕНЕРИИ ПО начинают срабатывать условные рефлексы. Изделие есть? да. Документация? Желающих покидаться калом могу сразу успокоить. Кто работал по гос. заказу - там пофик, ПО, железки или электроника. Разделы "изделие + документация". Хоть лабудень какую-то напиши, но документация в распечатанном виде должна лежать.
3. Ещё раз медленно. Мы сделали заказчику что-то - Болт М6. Он купил - не как в магазине. А купил "проект", т.е. документацию, позволяющую ИЗГОТОВИТЬ этот болт.
4. Программист (блин) синженерил что? код. Да, код является его продуктом, а не софт.
5. Ок, инструкцию пользователя (мануал и как хочешь это назови) выкинули. Говорим о документировании API. Зачем?
6. Зачем?
Ну типа документация позволяет правильно использовать/сокращает время на освоение API. А если и так всё понятно?
7. А если в контракте написано "документировать каждую функцию"? Контракт в широком смысле. Например, делать то, что "сказал Макс".
8. Берём достаточно абстрактного "Макса", который видит вас не первый раз, а ваш код - первый. И что? Кто будет нести затраты на определение, для какого конструктора пишем доку,а для какого нет?
Выплывает иррациональность с точки зрения программиста. Здесь ключевое слово "с точки зрения".
Например, нужна ли Дельфи документация.
Поверьте, я очень много общаюсь с дельфистами. Разговор начинается так:
- где докуменатция на Делфьи?
- а что ты подразумеваешь под этим?
- ну то, что там типа какие компоненты....
- ты хочешь "свойство Position.X задает расстояние от левой границы клиентской области окна (Parent-а) до левой границы области элемента управления"?
- не, не хочу.
- а что ты хочешь?
- ну... чтобы там было понятно как использовать.
- в виде чего?
- иди ты, Сева, нафик, вы там в Эмбаркадере сами придумайте, чтобы нам было хорошо.
диалог примерно такой в 80% случаев.
Ну а теперь обратно в абстрактные области.
Есть такое понятие "осознанность". Умение спрашивать "зачем", не находить ответа, а потом подниматься на уровень выше и опять спрашивать "зачем".
- Зачем я пишу тупую доку, никому не нужную?
- Так сказал начальник.
- Зачем так сказал начальник?
- Ему так проще жить.
- Можно пойти и сказать начальнику, что мы делаем херню?
- Зачем мне это надо?
- Зачем я делаю тупую документацию?
- Затем, что по договору с работодателем тебе платят за время, поэтому делай, что говорят и получай зарплату.
- Зачем я делаю тупую работу?
- Тебе за это платят деньги.
- Зачем мне деньги?
- Кормить семью.
- Зачем мне семья?
- Раньше надо было думать.
>Брат, ты бинарное дерево с обходом может по памяти написать, причем даже без не то, что отладки - проверки синтаксиса.
УдалитьВот по памяти, ничего сложного =)
data BT a = BT a (BT a) (BT a) | BTNull
instance Functor BT where
fmap f (BT x t1 t2) = BT (f x) (fmap f t1) (fmap f t2)
fmap _ BTNull = BTNull
Могу круче:
Удалитьuses BTree;
Можете - напишите. А модуль подключить любой может, писалось то не об этом. =)
Удалитьhttp://18delphi.blogspot.ru/2013/07/blog-post_2853.html
Удалить>http://18delphi.blogspot.ru/2013/07/blog-post_2853.html
Удалитьи к чему это?
А так - да, я видел, и даже комментировал.
... и чтобы бы не прослыть "занудой" маленькая история на прощанье.
ОтветитьУдалитьКак-то раз мы делали проект за деньги и во некой страны, славящейся подозрительностью к российским программистам.
У меня была какая-то ерунда, всего-то 3 000 строк кода. Правда по 3Д. Там всякая алгоритмика.
Заказчик попросил закомментировать КАЖДУЮ (не, не строчку) - ПЕРЕМЕННУЮ.
// цикл по количеству точек в массиве
// i - переменная-счётчик цикла
// n - количество точек в массиве
for(int i=0; i<n; i++) // на каждой итерации значение i увеличивается на 1
Ну, бывает, конечно, всякое.
УдалитьНо в общем случае (это лично моё мнение), документация (в виде комментариев к коду) должна быть уместна.
А про масло-масленое можно спорить бесконечно. Тут, наверное, надо отталкиваться от аудитории, на которую нацелена эта документация.
NameRec:
ОтветитьУдалить«Проблема - В ЯЗЫКЕ и СПОСОБЕ донесения.
…
UML оказался не "серебряной пулей" и не "окончательным решением", но он - ПОКА - наиболее удачен.»
– Собственно, я ждал этих слов :-)
Обозначу тезисно то, о чём говорил ранее:
1. Никто не против UML как инструмента проектирования и документирования.
Хорошая документация должна доносить информацию в форме, обеспечивающей лучшее и скорейшее понимание. Поэтому использование диаграмм там, где они уместны — приветствуется.
С другой стороны, не вижу причин идеализировать UML как при проектировании, так и при документировании. В ряде случаев код может оказаться проще соответствующих ему диаграмм. Могу даже указать на типаж таких случаев: когда важны технические аспекты реализации элементов диаграмм. Например, UML может указать на то, что объекты связаны и указать на тип этой связи, но он никак не регламентирует способ организации этой связи в коде. Именно по этой причине некоторые диаграммы автора (например, когда речь шла о контейнерах) оказываются чуть ли не сложнее кода, который по ним построен.
2. UML, по крайней мере, в том виде, в котором он задуман, был предназначен для проектирования, документирования, коммуникации, но не для программирования.
Автор предлагает интересный подход, позволяющий перейти от UML к программному коду, причём источником исходного кода является UML.
Такая увязка выглядит интересной, но возникают вопросы относительно накладных расходов, по поддержке такой связи. Важнейшим элементом увязки UML с кодом являются шаблоны, без которых не обойтись и которые, по крайне мере — мне, представляются дополнительным звеном в цепочке UML → код. Причём, чем «тяжелее» это звено, тем IMHO меньше ценность увязки UML с кодом.
3. UML не заменит документацию, поскольку хорошая документация помимо структуры классов и писания прецедентов должна описывать концепцию, идеологию системы.
Сами же диаграммы очень быстро становятся сложными по мере усложнения модели предметной области. Да, есть решения на счёт их упрощения, чаще всего, сводящиеся к иерархичности (как сделано в ARIS, например), но... :-)
Если мы вынуждены начинать «изобретать» способы по упрощению диаграмм, не стоит ли отказаться от них, как от описательного инструмента? Или понизить степень их детальности? Понятно, что связь с кодом здесь пропадёт, но так ли нужна эта связь с кодом?
4. Относительно тезиса, что:
Удалить«Далеко не все разработчики способны описать принципы работы "на человеческом языке"»
есть хороший опыт кураторства и выборочной проверки именно для «проектно-зависимых» библиотек.
С этими библиотеками постоянно работают разные программисты, с которыми руководство соответствующих уровней обязано иметь обратную связь.
Если некоторые решения вызывают затруднения в применении, впору поставить вопрос: они либо плохо организованы архитектурно, либо плохо документированы.
В обоих случаях можно предпринять необходимые меры по устранению и добиться от конкретных исполнителей приемлемого качества документирования. Разумеется, нал этим нужно работать.
Само же по себе применение UML (и кодогенерации) проблему здесь не решит. Совершенно.
Скорее, создаст дополнительную, поскольку шаблоны также онуждаются в документировании.
5. Тесты (как и UML) не годятся для замены документации, поскольку имеют другие целевые функции. Для тестов это — протестировать разработанную (или разрабатываемую — при экстремальном TDD) функциональность, UML – формально описать архитектуру и определить варианты использования, а для документации — максимально внятно изложить: что, где расположено, каким целям служит, из чего состоит и каким видится авторами применение этого.
Да, можно использовать UML и тесты для документирования, но IMHO это будет неравноценной подменой.
6. Относительно ценности UML как инструмента описания архитектуры я также не уверен.
Я даже не вижу (простите за крамолу) необходимости в полной картине архитектуры, представленной в каком-либо ином виде, нежели код.
«Код и есть дизайн» - это не я придумал.
Очень многие вопросы, касающиеся архитектуры можно уяснить для себя применением IDE (даже такой ужасной, как IDE Delphi). В ситуации неоднозначности следует привлекать документацию. А по моему опыту, те вопросы, которые в своё время вызывали затруднения (например, зачем нужны DataLink и почему они двух видов в VCL?) UML прояснить бы не смог.