|
698 / 572 / 75
Регистрация: 20.09.2014
Сообщений: 3,700
|
|
Идеальные комментарии в программе20.11.2020, 20:01. Показов 5001. Ответов 23
Метки нет (Все метки)
Интересуюсь технологиями и техниками в программировании. Один из вопросов интересных - какие правила для написания хороших комментариев в программе.
Есть правила для новичков - вроде "не пиши, что делает программа дословно", ну и правило, что хорошо названные имена переменных, функций и объектов должны избавить программу от комментариев вовсе. Последнее утверждение, конечно, ложь, так как человек, изучающий программу, может быть не в курсе предметной области. Например, может быть комментарий "А принтер этой модели не умеет печатать букву Ё!". Я уже в соседней теме писал, что меня интересует IDE/ЯП для программиста, а не для компилятора/процессора. В существующих языках комментарий - это простая строка с любой ахинеей, которая предназначена для программиста, но не для компилятора. И в определенный момент я понял, что в моей IDE комментариев не будет в том виде, как в существующих языках. В моей IDE (которой ещё почти нет) комментарии заменят неким образом структурированные комментарии. Моя цель - понять, как структурировать. Ну и главный вопрос - как понять, что комментарии завершены, достаточны и понятны?
0
|
|
| 20.11.2020, 20:01 | |
|
Ответы с готовыми решениями:
23
Комментарии к программе
комментарии к программе |
|
Просто Лис
|
||||||||||||||||||
| 21.11.2020, 11:18 | ||||||||||||||||||
0
|
||||||||||||||||||
|
698 / 572 / 75
Регистрация: 20.09.2014
Сообщений: 3,700
|
|||||||
| 21.11.2020, 12:34 [ТС] | |||||||
|
Мы привыкли, что комментарии - это просто набор произвольных букв. В этой теме предлагаю отвыкнуть.) Одна из простых идей - привязка комментария к любому элементу языка программирования. Мы помещаем комментарий сверху, снизу или справа от инструкции, точнее, строки с инструкцией или ее частью. Но не можем как-то удобно расположить комментарий, например, внутри вызова функции:
0
|
|||||||
|
Просто Лис
|
||||||||||||
| 21.11.2020, 12:44 | ||||||||||||
0
|
||||||||||||
|
698 / 572 / 75
Регистрация: 20.09.2014
Сообщений: 3,700
|
|
| 21.11.2020, 12:56 [ТС] | |
|
Ох уж это приверженство plain-text programming language!)))
Это мое определение для всех ЯП, к которым мы привыкли. Я намеренно стираю грань между IDE и ЯП, так как понимаю, что способы вывода и ввода информации - это тоже часть языка [программирования] и тоже подлежат стандартизации (как части языка). Добавлено через 1 минуту А вот картинка уже интереснее!
0
|
|
|
|
|
| 22.11.2020, 00:11 | |
|
0
|
|
|
698 / 572 / 75
Регистрация: 20.09.2014
Сообщений: 3,700
|
|
| 22.11.2020, 09:01 [ТС] | |
|
Я открыл пример доксигеновской документации http://dtris.sourceforge.net/d... index.html
Я не знаю, может проект действительно сложный, но понятного мало, особенно когда смотришь на супер-схему взаимосвязей. Я так понимаю, Доксиген использует комментарии в программе и сам код, чтобы сгенерировать документацию, и больше никакой информации. vantfiles, спасибо, может действительно Доксиген поможет быстрее выявить существующие проблемы комментирования. Теперь я хочу сформулировать принципы идеального комментирования: 1. Работу программы комментировать не надо, лучше применяй хорошие абстракции. 2. Прокомментируй окружение программы, информация о внешних системах не содержится в коде. 3. Неподготовленный программист способен самостоятельно проанализировать код и может что-то знать про окружение (просто побывав в этом самом окружении в качестве тестировщика). Однако, возможны ситуации, когда код действительно сложный, а окружение полноценно изучить, побывав в нем, затруднительно. Добавлено через 13 минут 4. Комментатор сам может не знать окружение, плохо разбираться в своей программе или не уделять достаточного внимания комментированию. На уровне IDE эта проблема должна и может быть решена. Для этого IDE должна контролировать соблюдение принципов комментирования, я уж не говорю, что помогать с абстракциями в коде.
0
|
|
|
Просто Лис
|
||||||||||||
| 22.11.2020, 09:27 | ||||||||||||
|
Если я прочитал описание документации и ничего не понял, то пойду искать примеры в этой же документации. В более худших случаях - ковырять тесты и копировать код оттуда. Если же ничего нет - то только тогда придётся вскрыть "чёрный ящик" и читать сам код.
0
|
||||||||||||
|
698 / 572 / 75
Регистрация: 20.09.2014
Сообщений: 3,700
|
|
| 22.11.2020, 10:27 [ТС] | |
|
Это вы про тот случай, когда алгоритм действительно сложный для понимания. А неподготовленный программист всё-таки может.
Добавлю ещё один принцип: 5. Программа является отражением (зеркалом) окружения. Но, как правило, неточным отражением. Это означает, что, описывая окружение, становится отчасти понятно, как должна работать (как работает) программа. Этот принцип восходит к принципу необходимого разнообразия систем Эшби. Но надо учитывать, что разнообразие не всегда необходимое.))) С 5-ым принципом гораздо интереснее. Попробую продемонстрировать на примере: В этой схеме все связи равнозначны, хотя фактически можно выделить основные связи, а часть обозначить как вспомогательные, дополнительные, связи "на всякий случай" и прочие категории. Берём и расставляем для всех связей веса-комментарии (компилятор не берет в расчет эти веса). Основные связи пожирнее отобразить, вспомогательные потоньше. Это комментирование кода непосредственно. Можно также описать через внешнее окружение: написать, что для игрока в 3Д-Тетрис важны изображение стакана, фигурок (игровая сцена) и кнопки управления. Всякие там окна Start и окна Gameover/Congratulation менее важны, подсчет игровых очков тоже не суть. Это тоже расставит веса объектам, функциям, переменным, связям. Этой информации нет ни в коде, и основная проблема - программисты не знают, что это важно для понимания. Самое правильное описание окружения программы - это математическая модель окружения. Однако это дорого, сложно и не совсем необходимо, так как программа является инверсным отражением окружения (почти). Если есть код программы, то необходимость в матмодели окружении частично отпадает. Следует добавить немного той информации, которой не видно в "зеркале". Сложно понять, всю эту околофилософскую чушь про "зеркало", "необходимое разнообразие" и т.д. Чтобы справиться с этой сложностью, я для себя принял, что часто важной информацией об окружении является распределение частот (вероятностей) входных переменных. Например, у пульта телевизора 40 кнопок, и распределение частот нажатий на кнопки смещено к тому используются в основном пять кнопок: Power, Vol+, Vol-, Ch+, Ch-. Эта информация помогает выделить главные функции в ПО телевизора. Компилятору эта информация не нужна, в коде эта информация не содержится.
0
|
|
|
698 / 572 / 75
Регистрация: 20.09.2014
Сообщений: 3,700
|
|
| 22.11.2020, 10:34 [ТС] | |
|
Рыжий Лис, сейчас доберёмся до ваших кусков программ. Вы правильно подметили, что абстракции скрывают детали реализации. Тогда решение такое: то, что скрыто под абстракцией, считать внешним окружением, и тогда все встаёт на свои места. При чем забавно, что это окружение имеет модель в виде кода, который можно подглядеть (не всегда).
0
|
|
|
Модератор
3132 / 2279 / 469
Регистрация: 26.03.2015
Сообщений: 8,870
|
||||
| 23.11.2020, 11:16 | ||||
|
Комментарии нужны: 1. Для функций (в C# такие комментарии начинаются с тройного слеша ///) 2. Иногда для переменных (если их назначение не очевидно из названия или использования) 3. Иногда для описания используемого алгоритма Первый вариант формализован в большинстве современных IDE, как мы можем видет на картинке из этого сообщения: Комментарии типа "function1(0 /* количество кошек */, a /* количество еды в килограммах */);" лишены смысла, так как это понятно 1) из названия аргументов функций, которые обычно можно увидеть в IDE 2) из комментариев первого типа (описание функции), которые тоже можно увидеть в IDE Что касается числовых литералов. Допустимы 0 и 1 для начальных значений. Допустимы 1/2 для слагаемых/множителей. Другие литералы заменяются на константы с говорящими названиями. (Есть исключения типа "перебираем нечётные числа", в которых смысл литерала +2 очевиден).
0
|
||||
|
Модератор
3132 / 2279 / 469
Регистрация: 26.03.2015
Сообщений: 8,870
|
||
| 23.11.2020, 11:28 | ||
|
Но есть ещё константы типа DefaultSize и т.п. Не должно быть кода типа "var a = new int[4];".
0
|
||
|
Просто Лис
|
||||||||||||
| 23.11.2020, 11:41 | ||||||||||||
0
|
||||||||||||
| 23.11.2020, 11:42 | |
|
Не по теме: Mikhaylo, не подскажете, в чем картинку рисовали в посте #10 ?
0
|
|
| 23.11.2020, 11:47 | |
|
Не по теме: Так картинку стащили отсюда: http://dtris.sourceforge.net/d... index.html
0
|
|
|
Модератор
3132 / 2279 / 469
Регистрация: 26.03.2015
Сообщений: 8,870
|
|
| 23.11.2020, 11:56 | |
|
0
|
|
|
698 / 572 / 75
Регистрация: 20.09.2014
Сообщений: 3,700
|
||
| 23.11.2020, 20:08 [ТС] | ||
|
Есть правда трудности формализации: 1. Программист частично знаком с внешней системой 2. Программисту трудно дается разбирательство с внутренним устройством программы. 3. Программа в какой-то степени отражает внешнюю систему. (Например, если принтер как внешняя система не печатает букву Ё, то в программе будет условие проверки "принтер=ххх AND буква=Ё, то буква=Е". А иногда бывает, что программа не отражает внешнюю систему, например, вычисление корня квадратного может не учитывать, что очень часто извлекается корень из 49. Можно было бы сделать отражающий код: если подкоренное число 49, то радикал = 7, иначе радикал = корень из подкоренного числа.) Очень важный пример программ, которые не отражают окружение, это некоторые универсальные алгоритмы, универсальные библиотеки. В них предполагается произвольность входных данных, то есть окружение абстрактно. И об этом нужно писать в комментариях, это же ведь информация о внешней системе. Добавлено через 25 минут Абсолютно противоположный пример - программы, реализующие алгоритм точного управления с разомкнутым контуром предопределенным объектом управления. Если объект управления описывается уравнением y = f(x), то для управления его поведением следует создать программу реализующую обратную функцию x=f-1(y*), где y* - целевое воздействие. В итоге система, состоящая из объекта управления и управляющей программы реализует функцию равенства целевой функции и реального поведения y = f(x) = f(f-1(y*)) = y*. Такая программа во всех отношениях отражает объект управления, который представляется как внешняя система для программы. Такая программа является идеальным объектом для принципа необходимого разнообразия Эшби. Сложно?) Добавлено через 7 минут Эти идеальные программы редко имеют место быть, это первый момент, но в то же время, без разницы, что описывать - внешнюю систему или внутреннюю, это второй момент. Так как зная одну из них, можно получить другую, используя простую математическую операцию обращения функции. И так как внутренняя система записана в виде кода, который не требует комментирования, то внешнюю систему не следует комментировать. Достаточно сказать, что она является однозначным отражением (обращением) программы. Или наоборот.
0
|
||
|
698 / 572 / 75
Регистрация: 20.09.2014
Сообщений: 3,700
|
||
| 24.11.2020, 08:31 [ТС] | ||
|
Заметьте: программист видит, что в функцию подставляется 0 и даже проанализировать может выполнение программы, но требуется комментарий. Причина - нет знания о внешней системе (добавили в игру необычный уровень или режим с невесомостью). То есть, всякие рассуждения, что комментарии можно полностью устранить хорошими абстракциями, неверны. Так как не всегда у программиста есть подробные знания о внешней системе. Эти знания можно давать не только текстом, но и фотографиями, видео, погружением непосредственно в систему (в геймплей, как в рассматриваемом примере).
0
|
||
| 24.11.2020, 08:31 | |
|
Помогаю со студенческими работами здесь
20
Комментарии к программе комментарии к программе Комментарии к программе. Комментарии к программе Комментарии к программе Искать еще темы с ответами Или воспользуйтесь поиском по форуму: |
|
Новые блоги и статьи
|
||||
|
PhpStorm 2025.3: WSL Terminal всегда стартует в ~
and_y87 14.12.2025
PhpStorm 2025. 3: WSL Terminal всегда стартует в ~ (home), игнорируя директорию проекта
Симптом:
После обновления до PhpStorm 2025. 3 встроенный терминал WSL открывается в домашней директории. . .
|
Как объединить две одинаковые БД Access с разными данными
VikBal 11.12.2025
Помогите пожалуйста !! Как объединить 2 одинаковые БД Access с разными данными.
|
Новый ноутбук
volvo 07.12.2025
Всем привет.
По скидке в "черную пятницу" взял себе новый ноутбук Lenovo ThinkBook 16 G7 на Амазоне:
Ryzen 5 7533HS
64 Gb DDR5
1Tb NVMe
16" Full HD Display
Win11 Pro
|
Музыка, написанная Искусственным Интеллектом
volvo 04.12.2025
Всем привет. Некоторое время назад меня заинтересовало, что уже умеет ИИ в плане написания музыки для песен, и, собственно, исполнения этих самых песен. Стихов у нас много, уже вышли 4 книги, еще 3. . .
|
От async/await к виртуальным потокам в Python
IndentationError 23.11.2025
Армин Ронахер поставил под сомнение async/ await. Создатель Flask заявляет: цветные функции - провал, виртуальные потоки - решение. Не threading-динозавры, а новое поколение лёгких потоков. Откат?. . .
|
|
Поиск "дружественных имён" СОМ портов
Argus19 22.11.2025
Поиск "дружественных имён" СОМ портов
На странице:
https:/ / norseev. ru/ 2018/ 01/ 04/ comportlist_windows/
нашёл схожую тему. Там приведён код на С++, который показывает только имена СОМ портов, типа,. . .
|
Сколько Государство потратило денег на меня, обеспечивая инсулином.
Programma_Boinc 20.11.2025
Сколько Государство потратило денег на меня, обеспечивая инсулином.
Вот решила сделать интересный приблизительный подсчет, сколько государство потратило на меня денег на покупку инсулинов.
. . .
|
Ломающие изменения в C#.NStar Alpha
Etyuhibosecyu 20.11.2025
Уже можно не только тестировать, но и пользоваться C#. NStar - писать оконные приложения, содержащие надписи, кнопки, текстовые поля и даже изображения, например, моя игра "Три в ряд" написана на этом. . .
|
Мысли в слух
kumehtar 18.11.2025
Кстати, совсем недавно имел разговор на тему медитаций с людьми. И обнаружил, что они вообще не понимают что такое медитация и зачем она нужна. Самые базовые вещи. Для них это - когда просто люди. . .
|
Создание Single Page Application на фреймах
krapotkin 16.11.2025
Статья исключительно для начинающих. Подходы оригинальностью не блещут.
В век Веб все очень привыкли к дизайну Single-Page-Application .
Быстренько разберем подход "на фреймах".
Мы делаем одну. . .
|