tag:blogger.com,1999:blog-3208941668630248550.post6432819760144047048..comments2024-03-13T10:43:06.615+02:00Comments on 18-ть лет с Delphi: Про документациюAlex W. Lulinhttp://www.blogger.com/profile/08400475846894229767noreply@blogger.comBlogger26125tag:blogger.com,1999:blog-3208941668630248550.post-48290525120893307862013-08-24T20:58:59.386+03:002013-08-24T20:58:59.386+03:00>http://18delphi.blogspot.ru/2013/07/blog-post_...>http://18delphi.blogspot.ru/2013/07/blog-post_2853.html<br />и к чему это?<br />А так - да, я видел, и даже комментировал.Son of a gunnoreply@blogger.comtag:blogger.com,1999:blog-3208941668630248550.post-47448944897518030542013-08-24T20:51:57.660+03:002013-08-24T20:51:57.660+03:00http://18delphi.blogspot.ru/2013/07/blog-post_2853...http://18delphi.blogspot.ru/2013/07/blog-post_2853.htmlAlex W. Lulinhttps://www.blogger.com/profile/08400475846894229767noreply@blogger.comtag:blogger.com,1999:blog-3208941668630248550.post-72857815843147361752013-08-24T20:36:37.550+03:002013-08-24T20:36:37.550+03:00Можете - напишите. А модуль подключить любой может...Можете - напишите. А модуль подключить любой может, писалось то не об этом. =)Son of a gunnoreply@blogger.comtag:blogger.com,1999:blog-3208941668630248550.post-75220080917402912182013-08-24T20:15:40.267+03:002013-08-24T20:15:40.267+03:00Могу круче:
uses BTree;Могу круче:<br /><br />uses BTree;Alex W. Lulinhttps://www.blogger.com/profile/08400475846894229767noreply@blogger.comtag:blogger.com,1999:blog-3208941668630248550.post-59857987339045024682013-08-24T19:48:57.256+03:002013-08-24T19:48:57.256+03:00>Брат, ты бинарное дерево с обходом может по па...>Брат, ты бинарное дерево с обходом может по памяти написать, причем даже без не то, что отладки - проверки синтаксиса. <br /><br />Вот по памяти, ничего сложного =)<br /><br />data BT a = BT a (BT a) (BT a) | BTNull<br /><br />instance Functor BT where<br /> fmap f (BT x t1 t2) = BT (f x) (fmap f t1) (fmap f t2)<br /> fmap _ BTNull = BTNull<br /><br />Son of a gunnoreply@blogger.comtag:blogger.com,1999:blog-3208941668630248550.post-81711948737741695112013-08-23T20:39:41.820+03:002013-08-23T20:39:41.820+03:004. Относительно тезиса, что:
«Далеко не все разраб...4. Относительно тезиса, что:<br />«Далеко не все разработчики способны описать принципы работы "на человеческом языке"»<br />есть хороший опыт кураторства и выборочной проверки именно для «проектно-зависимых» библиотек.<br />С этими библиотеками постоянно работают разные программисты, с которыми руководство соответствующих уровней обязано иметь обратную связь.<br />Если некоторые решения вызывают затруднения в применении, впору поставить вопрос: они либо плохо организованы архитектурно, либо плохо документированы.<br />В обоих случаях можно предпринять необходимые меры по устранению и добиться от конкретных исполнителей приемлемого качества документирования. Разумеется, нал этим нужно работать.<br />Само же по себе применение UML (и кодогенерации) проблему здесь не решит. Совершенно.<br />Скорее, создаст дополнительную, поскольку шаблоны также онуждаются в документировании.<br />5. Тесты (как и UML) не годятся для замены документации, поскольку имеют другие целевые функции. Для тестов это — протестировать разработанную (или разрабатываемую — при экстремальном TDD) функциональность, UML – формально описать архитектуру и определить варианты использования, а для документации — максимально внятно изложить: что, где расположено, каким целям служит, из чего состоит и каким видится авторами применение этого.<br />Да, можно использовать UML и тесты для документирования, но IMHO это будет неравноценной подменой.<br />6. Относительно ценности UML как инструмента описания архитектуры я также не уверен.<br />Я даже не вижу (простите за крамолу) необходимости в полной картине архитектуры, представленной в каком-либо ином виде, нежели код.<br />«Код и есть дизайн» - это не я придумал.<br />Очень многие вопросы, касающиеся архитектуры можно уяснить для себя применением IDE (даже такой ужасной, как IDE Delphi). В ситуации неоднозначности следует привлекать документацию. А по моему опыту, те вопросы, которые в своё время вызывали затруднения (например, зачем нужны DataLink и почему они двух видов в VCL?) UML прояснить бы не смог.Anonymousnoreply@blogger.comtag:blogger.com,1999:blog-3208941668630248550.post-20749082598289599662013-08-23T20:39:08.645+03:002013-08-23T20:39:08.645+03:00NameRec:
«Проблема - В ЯЗЫКЕ и СПОСОБЕ донесения....NameRec:<br /><br />«Проблема - В ЯЗЫКЕ и СПОСОБЕ донесения. <br />…<br />UML оказался не "серебряной пулей" и не "окончательным решением", но он - ПОКА - наиболее удачен.»<br />– Собственно, я ждал этих слов :-)<br />Обозначу тезисно то, о чём говорил ранее:<br />1. Никто не против UML как инструмента проектирования и документирования.<br />Хорошая документация должна доносить информацию в форме, обеспечивающей лучшее и скорейшее понимание. Поэтому использование диаграмм там, где они уместны — приветствуется.<br />С другой стороны, не вижу причин идеализировать UML как при проектировании, так и при документировании. В ряде случаев код может оказаться проще соответствующих ему диаграмм. Могу даже указать на типаж таких случаев: когда важны технические аспекты реализации элементов диаграмм. Например, UML может указать на то, что объекты связаны и указать на тип этой связи, но он никак не регламентирует способ организации этой связи в коде. Именно по этой причине некоторые диаграммы автора (например, когда речь шла о контейнерах) оказываются чуть ли не сложнее кода, который по ним построен.<br />2. UML, по крайней мере, в том виде, в котором он задуман, был предназначен для проектирования, документирования, коммуникации, но не для программирования.<br />Автор предлагает интересный подход, позволяющий перейти от UML к программному коду, причём источником исходного кода является UML.<br />Такая увязка выглядит интересной, но возникают вопросы относительно накладных расходов, по поддержке такой связи. Важнейшим элементом увязки UML с кодом являются шаблоны, без которых не обойтись и которые, по крайне мере — мне, представляются дополнительным звеном в цепочке UML → код. Причём, чем «тяжелее» это звено, тем IMHO меньше ценность увязки UML с кодом.<br />3. UML не заменит документацию, поскольку хорошая документация помимо структуры классов и писания прецедентов должна описывать концепцию, идеологию системы.<br />Сами же диаграммы очень быстро становятся сложными по мере усложнения модели предметной области. Да, есть решения на счёт их упрощения, чаще всего, сводящиеся к иерархичности (как сделано в ARIS, например), но... :-)<br />Если мы вынуждены начинать «изобретать» способы по упрощению диаграмм, не стоит ли отказаться от них, как от описательного инструмента? Или понизить степень их детальности? Понятно, что связь с кодом здесь пропадёт, но так ли нужна эта связь с кодом?Anonymousnoreply@blogger.comtag:blogger.com,1999:blog-3208941668630248550.post-38122540095148819212013-08-23T18:58:06.217+03:002013-08-23T18:58:06.217+03:00Ну, бывает, конечно, всякое.
Но в общем случае (эт...Ну, бывает, конечно, всякое.<br />Но в общем случае (это лично моё мнение), документация (в виде комментариев к коду) должна быть уместна.<br /><br />А про масло-масленое можно спорить бесконечно. Тут, наверное, надо отталкиваться от аудитории, на которую нацелена эта документация.Николай Зверевhttps://www.blogger.com/profile/08965247674233981930noreply@blogger.comtag:blogger.com,1999:blog-3208941668630248550.post-68252899716543636282013-08-23T18:54:27.443+03:002013-08-23T18:54:27.443+03:00Сева (можно уже на ты, да?), я тебя никогда никак ...Сева (можно уже на ты, да?), я тебя никогда никак не называл и уж тем более, не обзывал.<br />Я очень уважаю твой труд, и если чем-то случайно обидел - извини.Николай Зверевhttps://www.blogger.com/profile/08965247674233981930noreply@blogger.comtag:blogger.com,1999:blog-3208941668630248550.post-8776403847031780592013-08-23T18:52:39.340+03:002013-08-23T18:52:39.340+03:00> Нельзя ломать API
мне показалось, что речь о ...> Нельзя ломать API<br />мне показалось, что речь о коде. Если про API (сигнатура вызова и ожидаемый результат) - то конечно, лучше ничего не менять (ну с оговорками об области видимости этого API).Николай Зверевhttps://www.blogger.com/profile/08965247674233981930noreply@blogger.comtag:blogger.com,1999:blog-3208941668630248550.post-25140964201747832962013-08-23T17:22:02.363+03:002013-08-23T17:22:02.363+03:00... и чтобы бы не прослыть "занудой" мал...... и чтобы бы не прослыть "занудой" маленькая история на прощанье.<br /><br />Как-то раз мы делали проект за деньги и во некой страны, славящейся подозрительностью к российским программистам.<br /><br />У меня была какая-то ерунда, всего-то 3 000 строк кода. Правда по 3Д. Там всякая алгоритмика.<br /><br />Заказчик попросил закомментировать КАЖДУЮ (не, не строчку) - ПЕРЕМЕННУЮ. <br /><br />// цикл по количеству точек в массиве<br />// i - переменная-счётчик цикла<br />// n - количество точек в массиве<br />for(int i=0; i<n; i++) // на каждой итерации значение i увеличивается на 1Всеволод Леоновhttp://blogse.embarcdero.com/vsevolodleonovnoreply@blogger.comtag:blogger.com,1999:blog-3208941668630248550.post-55044792742859541842013-08-23T17:14:12.155+03:002013-08-23T17:14:12.155+03:00Каждый раз, когда мне программист говорит "за...Каждый раз, когда мне программист говорит "зачем?" мне хочется взять его за шиворот и... головой в монитор. Брат, ты бинарное дерево с обходом может по памяти написать, причем даже без не то, что отладки - проверки синтаксиса. Или 4-нарный JOIN написать. Про ассемблер вообще молчу. Давайте на данном примере включим лучшие отдела нашего мозга и не будем говорить "зачем".<br /><br />1. Документация в классической инженерии служит для того, чтобы можно было ИЗГОТОВИТЬ что-то. Пусть это будет болт М6. Чертеж? Да. Доп. документация. Технология. А потом по этой документации сделали деталь. Не? Ок, поправили документацию и ок.<br />2. Отсюда в ИНЖЕНЕРИИ ПО начинают срабатывать условные рефлексы. Изделие есть? да. Документация? Желающих покидаться калом могу сразу успокоить. Кто работал по гос. заказу - там пофик, ПО, железки или электроника. Разделы "изделие + документация". Хоть лабудень какую-то напиши, но документация в распечатанном виде должна лежать.<br />3. Ещё раз медленно. Мы сделали заказчику что-то - Болт М6. Он купил - не как в магазине. А купил "проект", т.е. документацию, позволяющую ИЗГОТОВИТЬ этот болт. <br />4. Программист (блин) синженерил что? код. Да, код является его продуктом, а не софт. <br />5. Ок, инструкцию пользователя (мануал и как хочешь это назови) выкинули. Говорим о документировании API. Зачем?<br />6. Зачем?<br />Ну типа документация позволяет правильно использовать/сокращает время на освоение API. А если и так всё понятно?<br />7. А если в контракте написано "документировать каждую функцию"? Контракт в широком смысле. Например, делать то, что "сказал Макс". <br />8. Берём достаточно абстрактного "Макса", который видит вас не первый раз, а ваш код - первый. И что? Кто будет нести затраты на определение, для какого конструктора пишем доку,а для какого нет?<br /><br />Выплывает иррациональность с точки зрения программиста. Здесь ключевое слово "с точки зрения". <br />Например, нужна ли Дельфи документация.<br />Поверьте, я очень много общаюсь с дельфистами. Разговор начинается так: <br />- где докуменатция на Делфьи?<br />- а что ты подразумеваешь под этим?<br />- ну то, что там типа какие компоненты....<br />- ты хочешь "свойство Position.X задает расстояние от левой границы клиентской области окна (Parent-а) до левой границы области элемента управления"?<br />- не, не хочу.<br />- а что ты хочешь?<br />- ну... чтобы там было понятно как использовать.<br />- в виде чего?<br />- иди ты, Сева, нафик, вы там в Эмбаркадере сами придумайте, чтобы нам было хорошо.<br /><br />диалог примерно такой в 80% случаев.<br /><br />Ну а теперь обратно в абстрактные области.<br />Есть такое понятие "осознанность". Умение спрашивать "зачем", не находить ответа, а потом подниматься на уровень выше и опять спрашивать "зачем".<br /><br />- Зачем я пишу тупую доку, никому не нужную?<br />- Так сказал начальник.<br />- Зачем так сказал начальник?<br />- Ему так проще жить.<br />- Можно пойти и сказать начальнику, что мы делаем херню?<br />- Зачем мне это надо?<br /><br />- Зачем я делаю тупую документацию?<br />- Затем, что по договору с работодателем тебе платят за время, поэтому делай, что говорят и получай зарплату.<br /><br />- Зачем я делаю тупую работу?<br />- Тебе за это платят деньги.<br />- Зачем мне деньги?<br />- Кормить семью.<br />- Зачем мне семья?<br />- Раньше надо было думать.<br />Всеволод Леоновhttp://blogs.embarcadero.com/vsevolodleonovnoreply@blogger.comtag:blogger.com,1999:blog-3208941668630248550.post-58205890666860998582013-08-23T16:47:35.041+03:002013-08-23T16:47:35.041+03:00Сейчас немного "грязи".
Как когда-то Ни...Сейчас немного "грязи". <br />Как когда-то Николай Зверев меня обозвал "нерукопожатным", так этим имиджем и пользуюсь.<br /><br />Проблема в том, что интеллект никак не помогает анализировать. Большинство жизненных задач очень тривиальны (в плане аналитики). Сначала я верил в программистов - но после Embarcadero и ряда насыщенных и кровавых тролль-битв несколько сменил точку зрения. Программисты, будучи высокими интеллектуалами, также легко попадаются на удочку "личностного восприятия". И не могут думать объективно. Мысленно себя надо поставить "над" (хотите? "вне") системы. Сейчас будет цепочка.Всеволод Леоновhttp://blogs.embarcadero.com/vsevolodleonovnoreply@blogger.comtag:blogger.com,1999:blog-3208941668630248550.post-71258408974202981472013-08-23T16:33:18.244+03:002013-08-23T16:33:18.244+03:00Будет "многобукв", джентельмены, но без ...Будет "многобукв", джентельмены, но без "предварительного застирывания" не получается.<br /><br />Постановка вопроса - "зачем такая документация". Ответ простой. Ничего не бывает немотивированным способом. Если нет рациональности в поступках/деятельности, то это потому, что вы её не видите. Это не оскорбление, это - факт. Я даже готов слегка пожертвовать имиджем Embarcadero, т.к. компания для меня не идол, а средство быть в IT. <br /><br />Если вы что-то "продаёте", то очень часто ФАКТ НАЛИЧИЯ фичи важнее, чем её полезность. Начиная от тупого 80/20 и заканчивая правилом "трёх сигма", нормальным законом распределения, сложностью (ли) человеческой психики, "правилом золотой рыбки" и пр. пр. пр. <br /><br />Отсюда проистекает: "безобразно и однообразно". Представьте, что вы даёте пользователю что-то c API(наплевать что, пусть "пульт от телевизора"), где есть сложные кнопки, а есть простые. Ну ка в инструкции (=документации) вы опишите 5 сложных кнопок, а 10 простых просто "забудете".<br /><br />Что мы получим на выходе? Большое пользовательское "спасибо" и вечный троллинг на тему "они даже доки писать не могут, куда им пульты делать! а уже про телевизоры вообще молчим")Всеволод Леоновhttp://blogs.embarcadero.com/vsevolodleonovnoreply@blogger.comtag:blogger.com,1999:blog-3208941668630248550.post-13856881649545609592013-08-23T15:59:37.126+03:002013-08-23T15:59:37.126+03:00>Это очень походит на принцип write only при ко...>Это очень походит на принцип write only при кодировании. >Далеко с таким принципом не уедешь.<br />под write only кодом обычно понимают нечитаемый код. Здесь совсем другой случай. Нельзя ломать API, вот и всё. И ничего нового здесь нет - это базовый принцип.Son of a gunnoreply@blogger.comtag:blogger.com,1999:blog-3208941668630248550.post-30627115047612823232013-08-23T15:54:48.037+03:002013-08-23T15:54:48.037+03:00>UML оказался не "серебряной пулей" и...>UML оказался не "серебряной пулей" и не "окончательным решением", но он - ПОКА - наиболее удачен.<br />UML не замена документации, и необходимость документирования не отменяет.<br />>Простите, но это мне - СМЕШНО. Наверное я чего-то не понимаю.<br />>Вам правда удаётся такое?<br />Конечно, это же один из базовых принципов. По другому - никак.<br />>Можно вопрос? Вы САМИ много кода написали?<br />Достаточно.Son of a gunnoreply@blogger.comtag:blogger.com,1999:blog-3208941668630248550.post-47092782782554030702013-08-23T13:35:27.734+03:002013-08-23T13:35:27.734+03:00> "Лучше безобразно, но однообразно."...> "Лучше безобразно, но однообразно."<br />Меня всегда передёргивает от этого выражения. Лучше однообразно и не безобразно. Безобразно лучше вообще не делать. ИМХО )<br /><br />> существующие функции менятся не должны вообще<br />Это очень походит на принцип write only при кодировании. Далеко с таким принципом не уедешь.Николай Зверевhttps://www.blogger.com/profile/08965247674233981930noreply@blogger.comtag:blogger.com,1999:blog-3208941668630248550.post-14788545351087374772013-08-22T23:13:03.261+03:002013-08-22T23:13:03.261+03:00"Подобного рода текст любой программист в сос..."Подобного рода текст любой программист в состоянии написать."<br />-- мне кажется, что вы просто судите по себе :-) А в мире есть и такие как я :-)<br /><br />Можно вопрос?<br />Вы САМИ много кода написали? Задокументировали? "Продали"?<br /><br />Это не попытка "фаллометрии". Это мне ПРОСТО НЕИНТЕРЕСНО.<br /><br />Просто мне хочется знать "метрики" и ГДЕ Я ОШИБАЮСЬ.Alex W. Lulinhttps://www.blogger.com/profile/08400475846894229767noreply@blogger.comtag:blogger.com,1999:blog-3208941668630248550.post-77807995222160625502013-08-22T23:10:20.524+03:002013-08-22T23:10:20.524+03:00"Лучше безобразно, но однообразно."
-- т..."Лучше безобразно, но однообразно."<br />-- тут - сложно не согласится, я сам так считаю. Но не стоит ничего доводить до "абсолюта" (ИМХО). Да и времени - жалко.Alex W. Lulinhttps://www.blogger.com/profile/08400475846894229767noreply@blogger.comtag:blogger.com,1999:blog-3208941668630248550.post-2045836882418294052013-08-22T23:09:09.228+03:002013-08-22T23:09:09.228+03:00"Вы так говорите, будто это описание затрудня..."Вы так говорите, будто это описание затрудняет понимание."<br />-- не затрудняет, но это - ТРАТА ВРЕМЕНИ, которого и так - КРАЙНЕ НЕМНОГО.<br /><br />Ну это - моё мнение.Alex W. Lulinhttps://www.blogger.com/profile/08400475846894229767noreply@blogger.comtag:blogger.com,1999:blog-3208941668630248550.post-6458375060091312432013-08-22T23:03:06.043+03:002013-08-22T23:03:06.043+03:00"а существующие функции менятся не должны воо..."а существующие функции менятся не должны вообще."<br /><br />Простите, но это мне - СМЕШНО. Наверное я чего-то не понимаю.<br /><br />Вам правда удаётся такое?Alex W. Lulinhttps://www.blogger.com/profile/08400475846894229767noreply@blogger.comtag:blogger.com,1999:blog-3208941668630248550.post-52762743454548679792013-08-22T23:01:53.252+03:002013-08-22T23:01:53.252+03:00"Подобного рода текст любой программист в сос..."Подобного рода текст любой программист в состоянии написать."<br /><br />Есть некоторые анонимы, которые своим тоном не очень располагают к общению. Простите уж.<br /><br />Но я всё же отвечу.<br /><br />Я САМ написал много фреймворков и библиотек.<br /><br />И я их "продавал" коллегам с тем или иным переменным успехом. Что-то продал, что-то нет.<br /><br />Но по-любому - качеством "продажи" (и документации - я недоволен). Может быть коллеги - откомментируют это (если захотят).<br /><br />Я пробовал и xHelpGen и Doc'o'Matic. И много чего ещё.<br /><br />Проблема - НЕ в инструментах.<br /><br />Проблема - В ЯЗЫКЕ и СПОСОБЕ донесения.<br /><br />Так что - можете считать меня дебилом :-)<br /><br />UML оказался не "серебряной пулей" и не "окончательным решением", но он - ПОКА - наиболее удачен.<br /><br />Только и всего.<br /><br />Хотя - опять же - может быть меня коллеги поправят. Если захотят. Ну или сочтут нужным.Alex W. Lulinhttps://www.blogger.com/profile/08400475846894229767noreply@blogger.comtag:blogger.com,1999:blog-3208941668630248550.post-62029965460551647452013-08-22T18:21:15.282+03:002013-08-22T18:21:15.282+03:00>Такие библиотеки гораздо чаще меняются.
В допо...>Такие библиотеки гораздо чаще меняются.<br />В дополнении документации нет ничего страшного, а существующие функции менятся не должны вообще.<br />>Далеко не все разработчики способны описать принципы работы "на человеческом языке"<br />Подобного рода текст любой программист в состоянии написать.Son of a gunnoreply@blogger.comtag:blogger.com,1999:blog-3208941668630248550.post-85936271209194419772013-08-22T15:43:46.426+03:002013-08-22T15:43:46.426+03:00>Документация - конечно - полезное дело.
>Но...>Документация - конечно - полезное дело.<br />>Но не в таком виде:<br />Вы так говорите, будто это описание затрудняет понимание. Между тем хоть какое-то описание в этой документации есть у любого метода, и это несомненно - плюс. "Лучше безобразно, но однообразно."<br />>Текстовая документация далеко не всегда показывает СВЯЗИ между проектными классами.<br />Связи между классами это вообще основа документации.Son of a gunnoreply@blogger.comtag:blogger.com,1999:blog-3208941668630248550.post-2459513676739552013-08-22T11:34:04.341+03:002013-08-22T11:34:04.341+03:00:-):-)Alex W. Lulinhttps://www.blogger.com/profile/08400475846894229767noreply@blogger.com