КАКАЯ ДОКУМЕНТАЦИЯ
ТРЕБУЕТСЯ?
• Чтобы использовать программу. Каждому пользователю требуется словесное описание программы
• Назначение. Что является главной функцией программы и причиной ее написания?
• Среда. На каких машинах, аппаратных конфигурациях и конфигурациях операционной системы будет она
работать?
• Область определения и область значений. Каковы допустимые значения входных данных? Какие правильные
значения выходных результатов могут появиться?
• Реализованные функции и использованные алгоритмы. Что конкретно может делать программа?
• Форматы ввода-вывода, точные и полные.
• Инструкция по работе, в том числе описание вывода на консоль и устройство вывода при нормальном и
аварийном завершении.
• Опции. Какой выбор предоставляется пользователю в отношении функций? Каким образом нужно его
Советы предпринимателям: индустриальный сертификат
задавать?
• Время работы. Сколько времени занимает решение задачи заданного размера на заданной конфигурации?
• Точность и проверка. Какова ожидаемая точность результатов? Какие имеются средства проверки точности?
3.
ОПРЕДЕЛЕНИЕ
• Самодокументирующие программы – это один из основных
принципов обработки данных учит, что безрассудно стараться
поддерживать синхронность независимых файлов. Значительно
лучше собрать их в один файл, в котором каждая запись содержит
все данные их обоих файлов, относящиеся к данному ключу.
4.
ПОДХОД
• Первое предложение
состоит в том, чтобы
разделы программы,
обязанные присутствовать в
ней согласно требованиям
языка программирования,
содержали как можно
больше документации.
Соответственно, метки,
операторы объявления и
символические имена
включают в задачу передать
читателю как можно
больше смысла.
5.
ПОДХОД
• Второе предложение — в максимальной мере использовать
пространство и формат, чтобы улучшить читаемость и показать
отношения подчиненности и вложенности.
• Третье предложение — включить в программу необходимую
текстовую документацию в виде параграфов комментариев. В
большинстве программ достаточно иметь построчные комментарии.
В программах, отвечающих жестким стандартам организаций на
«хорошее документирование», их часто слишком много. Однако
даже в этих программах обычно недостаточно параграфов
комментариев, которые действительно способствуют понятности и
обозримости целого.
6.
РАЗРАБОТКА ПРОГРАММЫ
• Поскольку документация встраивается в
используемые программой структуру, имена и
форматы, значительную часть этой работы
необходимо проделать, когда программу только
Что такое сертификат соответствия? Что такое сертификация?
начинают писать. Но именно тогда и нужно писать
документацию. Поскольку подход на основе
самодокументирования сокращает дополнительную
работу, меньше препятствий к его осуществлению.
7.
НЕКОТОРЫЕ ПРИЕМЫ
Используйте для каждого запуска свое имя задания и ведите журнал, в котором учитывайте предмет проверки, время и полученные результаты. Если имя состоит из мнемоники
(здесь QLT) и числового суффикса (здесь 4), то суффикс можно использовать в качестве номера запуска, связывающего запись в журнале и листинг. При этом для разных
прогонов требуются свои карты задания, но их можно делать колодами с дублированием постоянных данных.
Используйте мнемонические названия программы, включающие идентификатор версии — в предположении, что будет несколько версий. Здесь индекс — две младшие цифры года.
Включите текстовое описание в качестве комментариев к PROCEDURE.
Для документирования алгоритмов ссылайтесь, где можно, на литературу. Это экономит место, адресует к более полному освещению, чем можно дать в программе, и дает
возможность знающему читателю пропустить ссылку, оставляя уверенность, что он вас поймет.
Покажите связь с алгоритмом, описанным в книге: а) изменения; б) особенности использования; в) представление данных.
Объявите все переменные. Используйте мнемонику. Используйте комментарии для превращения оператора DECLARE в полноценную легенду. Обратите внимание, что он уже
содержит имена и описания структур, нужно лишь дополнить его описаниями назначения. Сделав это здесь, вы избежите отдельного повторения имен и структурных описаний.
Поставьте метку в начале инициализации.
Поставьте метки перед группами операторов, соответствующие операторам алгоритма, описанного в книге.
Используйте отступы для показа структуры и группирования.
Вручную поставьте стрелки, показывающие логический порядок операторов. Они очень полезны при отладке и внесении изменений. Их можно поместить на правом поле места
для комментариев и сделать частью вводимого в машину текста.
Вставьте строчные комментарии для пояснения всего, что неочевидно. При использовании изложенных выше приемов они окажутся короче и малочисленней, чем обычно.
Помещайте несколько операторов на одной строке или один оператор на нескольких строках в соответствии с логической группировкой, а также, чтобы показать связь с
описанием алгоритма
8.
ВОЗРАЖЕНИЯ
• Возражения. Каковы недостатки такого подхода к документированию? Они
существуют, и в прежние времена были существенными, но сейчас
становятся мнимыми.
• Самым серьезным возражением является увеличение размера исходного
текста, который нужно хранить. Поскольку практика все более тяготеет к
хранению исходного кода в активных устройствах, это вызывает растущее
беспокойство. Лично я пишу более краткие комментарии в программах на
APL, которые хранятся на диске, чем в программах на PL/I, которые хранятся
на перфокартах.
• Однако одновременно мы движемся к хранению в активных устройствах
текстовых документов, доступ к которым и изменение осуществляется с
помощью компьютеризированных текстовых редакторов. Как указывалось
выше, слияние текста и программы сокращает общее количество хранимых
символов.
9.
ЗАКЛЮЧЕНИЕ
• Подход на основе самодокументирования стимулирован
применением языков высокого уровня и обретает
наибольшую мощь и наивысшее оправдание в языках
высокого уровня, используемых в режиме он-лайн, будь то в
пакетном режиме или интерактивно. Как я доказывал, такие
языки, и системы очень сильно облегчают жизнь
программистов. Поскольку машины сделаны для людей, а
не люди для машин, их использование оправдано как с
экономической точки зрения, так и чисто по-человечески.
Источник: ppt-online.org
Самодокументирующие программы — презентация
Первый слайд презентации: Самодокументирующие программы
Изображение слайда
Слайд 2: Какая документация требуется?
Чтобы использовать программу. Каждому пользователю требуется словесное описание программы Назначение. Что является главной функцией программы и причиной ее написания? Среда. На каких машинах, аппаратных конфигурациях и конфигурациях операционной системы будет она работать?
Область определения и область значений. Каковы допустимые значения входных данных? Какие правильные значения выходных результатов могут появиться? Реализованные функции и использованные алгоритмы. Что конкретно может делать программа?
Форматы ввода-вывода, точные и полные. Инструкция по работе, в том числе описание вывода на консоль и устройство вывода при нормальном и аварийном завершении. Опции. Какой выбор предоставляется пользователю в отношении функций? Каким образом нужно его задавать? Время работы.
Сколько времени занимает решение задачи заданного размера на заданной конфигурации? Точность и проверка. Какова ожидаемая точность результатов? Какие имеются средства проверки точности ?
Изображение слайда
Слайд 3: Определение
Самодокументирующие программы – это один из основных принципов обработки данных учит, что безрассудно стараться поддерживать синхронность независимых файлов. Значительно лучше собрать их в один файл, в котором каждая запись содержит все данные их обоих файлов, относящиеся к данному ключу.
Изображение слайда
Слайд 4: Подход
Первое предложение состоит в том, чтобы разделы программы, обязанные присутствовать в ней согласно требованиям языка программирования, содержали как можно больше документации. Соответственно, метки, операторы объявления и символические имена включают в задачу передать читателю как можно больше смысла.
Изображение слайда
Слайд 5: подход
Второе предложение — в максимальной мере использовать пространство и формат, чтобы улучшить читаемость и показать отношения подчиненности и вложенности. Третье предложение — включить в программу необходимую текстовую документацию в виде параграфов комментариев. В большинстве программ достаточно иметь построчные комментарии. В программах, отвечающих жестким стандартам организаций на «хорошее документирование», их часто слишком много. Однако даже в этих программах обычно недостаточно параграфов комментариев, которые действительно способствуют понятности и обозримости целого.
Изображение слайда
Слайд 6: Разработка программы
Поскольку документация встраивается в используемые программой структуру, имена и форматы, значительную часть этой работы необходимо проделать, когда программу только начинают писать. Но именно тогда и нужно писать документацию. Поскольку подход на основе самодокументирования сокращает дополнительную работу, меньше препятствий к его осуществлению.
Изображение слайда
Слайд 7: Некоторые приемы
Используйте для каждого запуска свое имя задания и ведите журнал, в котором учитывайте предмет проверки, время и полученные результаты. Если имя состоит из мнемоники (здесь QLT) и числового суффикса (здесь 4), то суффикс можно использовать в качестве номера запуска, связывающего запись в журнале и листинг.
При этом для разных прогонов требуются свои карты задания, но их можно делать колодами с дублированием постоянных данных. Используйте мнемонические названия программы, включающие идентификатор версии — в предположении, что будет несколько версий. Здесь индекс — две младшие цифры года. Включите текстовое описание в качестве комментариев к PROCEDURE.
Для документирования алгоритмов ссылайтесь, где можно, на литературу. Это экономит место, адресует к более полному освещению, чем можно дать в программе, и дает возможность знающему читателю пропустить ссылку, оставляя уверенность, что он вас поймет. Покажите связь с алгоритмом, описанным в книге: а) изменения; б) особенности использования; в) представление данных.
Объявите все переменные. Используйте мнемонику. Используйте комментарии для превращения оператора DECLARE в полноценную легенду. Обратите внимание, что он уже содержит имена и описания структур, нужно лишь дополнить его описаниями назначения. Сделав это здесь, вы избежите отдельного повторения имен и структурных описаний. Поставьте метку в начале инициализации.
Поставьте метки перед группами операторов, соответствующие операторам алгоритма, описанного в книге. Используйте отступы для показа структуры и группирования. Вручную поставьте стрелки, показывающие логический порядок операторов. Они очень полезны при отладке и внесении изменений.
Их можно поместить на правом поле места для комментариев и сделать частью вводимого в машину текста. Вставьте строчные комментарии для пояснения всего, что неочевидно. При использовании изложенных выше приемов они окажутся короче и малочисленней, чем обычно. Помещайте несколько операторов на одной строке или один оператор на нескольких строках в соответствии с логической группировкой, а также, чтобы показать связь с описанием алгоритма
Изображение слайда
Слайд 8: Возражения
Возражения. Каковы недостатки такого подхода к документированию? Они существуют, и в прежние времена были существенными, но сейчас становятся мнимыми. Самым серьезным возражением является увеличение размера исходного текста, который нужно хранить. Поскольку практика все более тяготеет к хранению исходного кода в активных устройствах, это вызывает растущее беспокойство.
Лично я пишу более краткие комментарии в программах на APL, которые хранятся на диске, чем в программах на PL/I, которые хранятся на перфокартах. Однако одновременно мы движемся к хранению в активных устройствах текстовых документов, доступ к которым и изменение осуществляется с помощью компьютеризированных текстовых редакторов. Как указывалось выше, слияние текста и программы сокращает общее количество хранимых символов.
Изображение слайда
Слайд 9: Заключение
Подход на основе самодокументирования стимулирован применением языков высокого уровня и обретает наибольшую мощь и наивысшее оправдание в языках высокого уровня, используемых в режиме он- лайн, будь то в пакетном режиме или интерактивно. Как я доказывал, такие языки, и системы очень сильно облегчают жизнь программистов. Поскольку машины сделаны для людей, а не люди для машин, их использование оправдано как с экономической точки зрения, так и чисто по-человечески.
Источник: showslide.ru
Самодокументируемый код – это (как правило) чушь
Предваряя сегодняшнюю переводную публикацию, сразу отметим, что этот текст задуман как follow-up недавнему дискуссионному материалу «Прекратите усердствовать с комментариями в коде». Нас настолько впечатлила развернувшаяся там дискуссия и 189 комментариев по состоянию на 19.07.2019, что мы решили дать здесь слово и другому автору с портала Medium (Кристоферу Лейну), который практически по всем принципиальным вопросам полемизирует с тезисами Брайана Норлендера, автора первой статьи. Отметим, что в оригинале данная статья вышла на месяц позже предыдущей (16 мая и 16 июня), но собрала практически вдвое меньше аплодисментов (706 против 1,5K на момент публикации перевода). Посмотрим, что будет на Хабре…
Снимок взят с сайта rawpixels.com от автора Pexels
Я внимательно прочел отличную статью Синди Чеунг о технической документации и о том, почему разработчики должны лучше объяснять собственный код – и должен сказать, что полностью с ней согласен.
Я уже чертовски долго подвизаюсь в этом вашем IT, и мой опыт подсказывает, что есть в нашем деле такой самообман, которому разработчики и инженеры просто не в силах сопротивляться.
Мой код самодокументирующийся — Заблуждающийся разраб
В теории код хорошего инженера должен быть настолько ясен и удобочитаем, что ни в какой документации просто не нуждается.
Знаете, это чушь… как правило.
Почему «самодокументирующийся код» — это чушь?
Допустим, вы пишете код так же круто, как Хемингуэй писал прозу. Возможно, ваш код супер-пупер чистый и понятный (другому разработчику). В конце концов, этот код написан технарем для технаря, и, независимо от того, каким чистым и лаконичным может казаться ваш код, он все равно не предназначен для чтения не-программистами, которые могли бы проворчать: «что, черт возьми, все это значит?!»
Почему же я считаю, что самодокументирующийся код – это полная ерунда? Позвольте изложить в деталях.
Причина 1: В программировании полно всяких приемчиков, которые не самодокументируются
Просто потому, что большинство людей, и разработчики в том числе – не машины. Да, скорее всего я продерусь через ваш код, верно пойму названия ваших методов и классов, даже пойму, что именно вы делаете в каждом методе.
Но код пишут ДЛЯ машин. Они куда лучше нас разбираются, что с ним делать, и именно для того, чтобы описать им это, у нас есть языки программирования. С людьми же нужно общаться на более человеческом языке, чтобы человек смог понять, что делает ваш софт.
Между «читаю код и вижу, что в нем происходит» и документацией – очень большая разница. В коде можно со всеми подробностями прописать, что в нем делается, но можно ли в таком случае называть его «самодокументирующимся»? Думаю, каждому понятно, что нельзя.
Рассмотрим следующий простой блоб на C#. Я считываю файл, получаю его содержимое, а затем получаю кодировку файла при помощи StreamReader.
var fileContents = “”; Encoding fileEncoding; using (var reader = new StreamReader(filePath, Encoding.Default, true))
Если абстрагироваться от возможных неясностей со StreamReader, в остальном этот код достаточно прост, верно? Тогда… помилуйте, а что делается в этой строке?
reader.Peek();
Оказывается, считыватель должен совершить это действие, чтобы получить кодировку файла. Скажите, где тут самодокументация? Но достаточно потратить какие-нибудь 10 секунд, чтобы код стал гораздо понятнее.
reader.Peek(); //Вот так нужно заглянуть в файл, чтобы получить его кодировку.
Это всего лишь один пример, причем, чертовски простой. По мере того, как ваш код усложняется, такие мелкие детали начинают всплывать повсюду и постепенно захламляют некогда чистый код. Человеку, который будет его читать, становится все сложнее улавливать, что в коде происходит.
Причина 2: Сложность по сути своей не самодокументируется
Если вам доводилось писать файлы BASH или BAT, то вы знаете, что действия, изложенные в таком файле, выполняются последовательно. Одна задача за другой. Файл напоминает коротенькую историю, которая читается от первой до последней строчки.
Однако, если вы пишете программу, и в особенности – веб-приложение, такой последовательной истории там не будет, если не считать кода для начальной загрузки и конфигурации всех веб-сервисов.
Сами классы, образующие современное веб-приложение, не выполняются последовательно. В сущности, они представляют собой совокупность веб- или API-контроллеров, вызываемых именно в процессе взаимодействия клиента с веб-приложением.
Каждый веб- или API-контроллер может предусматривать потоки выполнения, при которых ответвляются новые процессы, отсылаются сообщения другим сервисам, ожидаются отклики, чтобы по их результатам сработали веб-хуки у слушателей. Ничто это и близко невозможно изложить в «сюжетном» формате. Из всего вашего «самодокументирующегося кода» новичок или не-программист выудит только «кажется, я понимаю, что тут происходит». Опять же, едва ли кто-то решится доверять подобной «документации».
Чем сложнее ваше приложение, тем выше вероятность, что его классы, методы и весь каркас не будут работать в последовательном режиме. Полагая, что любой, кто столкнется с таким приложением, легко поймет из кода, что в нем происходит, вы вступаете на все более скользкую дорожку.
Причина 3: Синтаксис языков программирования в принципе не назовешь удобочитаемым
Просто взгляните на эту функцию jquery, вызывающую конечную точку API.
var myURL=»https://some.url/path?access_token=my_token»; $.ajax(< url: myURL+», data: «message https://www.websequencediagrams.com/?source=post_page—————————«>websequencediagrams.com, где в простом текстовом формат можно описывать отличные диаграммы последовательностей – и затем их создавать.
Текст
title Service one to service two Service two requester -> Service two http client: Get Contract Service two http client -> Service one REST API: GET /api/contracts/ Service one REST API -> Service one app logic: get Contract with id 123 Service one app logic -> Service one REST API: Contract Service one REST API -> Service one REST API: Serialise to JSON / XML / etc. Service one REST API -> Service two http client: Serialised data Service two http client -> Service two http client : Deserialise to Contract Service two http client -> Service two requester: Contract
Диаграмма, которая из него получается
Избитая фраза о том, что одна картинка стоит тысячи слов – тем не менее, верна. Подобные диаграммы и блок-схемы помогут не-программисту разобраться в поведении вашего приложения, и для этого ему нужно будет всего лишь внимательно изучить картинку. Коллеги это оценят, а с вашей стороны это будет небольшая инвестиция в общее дело.
Этап 3: Называйте ваши классы и действия на Едином Языке (Ubiquitous Language)
Как известно, Единый Язык – это концепция из DDD (предметно-ориентированного проектирования), где команде и пользователям требуется выработать язык, который описывал бы все классы и их взаимодействия. Такой язык понятен неспециалисту, поэтому клиенты, тестировщики, инструкторы и представители бизнеса смогут на нем прочитать и понять, что именно делает наша программа и каким образом решает проблемы пользователя в данной предметной области.
После того, как Единый Язык согласован, вы должны добиться, чтобы все ваши классы, их методы, события и все остальное именовались настолько близко к Единому Языку, насколько это возможно.
/// /// Клиент сам отвечает за собственный вход в систему/выход из нее, а также за извлечение информации из своего профиля и управление ею /// settings /// public interface ICustomer < TaskLogin(string username, EncryptedString password); Task Logout(); Task GetMyProfile(); Task SaveMyProfile(CustomerProfileInformation); Task GetMySettings(); Task SaveMySettings(CustomerSettings);
Хотя, это просто фрагмент кода, над ним простым и общепонятным языком написано, что здесь происходит.
Этап 4: Просто напишите комментарии
Если все вышеперечисленное кажется вам слишком, слишком обременительным – просто снабдите ваш код информативными комментариями. Возможно, прямо сейчас они вам не понадобятся (вы-то сейчас с головой погружены в код, вам и так все ясно), но в будущем они могут вам весьма пригодиться.
Всего нескольких правильно расставленных строк с комментариями, комментария к классу или методу, будет достаточно, чтобы код стал намного понятнее. Я не призываю вас комментировать каждую строку (от этого код только усложнится). Просто сопроводите комментариями самые сложные участки кода, чтобы тот, кто будет через него пробираться, понимал, куда этот код его приведет.
Надеюсь, эти советы будут вам полезны
- Блог компании Издательский дом «Питер»
- Программирование
- C#
- ООП
Источник: habr.com