Идеальные комментарии в программе

Интересуюсь технологиями и техниками в программировании. Один из вопросов интересных - какие правила для написания хороших комментариев в программе.
Есть правила для новичков - вроде "не пиши, что делает программа дословно", ну и правило, что хорошо названные имена переменных, функций и объектов должны избавить программу от комментариев вовсе.

Последнее утверждение, конечно, ложь, так как человек, изучающий программу, может быть не в курсе предметной области. Например, может быть комментарий "А принтер этой модели не умеет печатать букву Ё!".

Я уже в соседней теме писал, что меня интересует IDE/ЯП для программиста, а не для компилятора/процессора. В существующих языках комментарий - это простая строка с любой ахинеей, которая предназначена для программиста, но не для компилятора. И в определенный момент я понял, что в моей IDE комментариев не будет в том виде, как в существующих языках. В моей IDE (которой ещё почти нет) комментарии заменят неким образом структурированные комментарии. Моя цель - понять, как структурировать. Ну и главный вопрос - как понять, что комментарии завершены, достаточны и понятны?

0

Сообщение от Mikhaylo Не знаю, я формализовал.

Не поддаются формализации - значит, нельзя определить, когда они нужны, а когда нет, и структура комментария - произвольный текст.

Например, в алгоритме быстрой тестировки:
Нужен здесь комментарий или не нужен? Текст, очевидно, произвольный.

Сообщение от Mikhaylo Сложно?)

Да. Я вообще ничего не понял.

0

Сообщение от Shamil1 Нужен здесь комментарий или не нужен? Текст, очевидно, произвольный.

Анализируем, кому адресован комментарий: осознаем степень его понимания внешней системы и степень способности понять, что происходит в коде. Кому-то будет непонятно, как это int p=1.5. Короче, для школьников надо комментарий, для студентов - нет. Но так как абстракции плохие, то комментировать надо, если конечно перед этим 100 раз рядом не комментировалось про интервал [i, j]. Помимо абстракций неплохо указать явно преобразование целых чисел в Float и обратно.

Сообщение от Shamil1 Да. Я вообще ничего не понял.

Нужно комментировать внешние системы, именно оттуда аналитики берут требования к работе программы. Например, присвоили переменной p значение 0.2, тогда комментарий - "наши аналитики провели исследование и решили, что оптимальное значение колеблется в диапазоне 0.1...0.3."
Заметьте, комментарий почти нисколько не связан с описанием действия в коде, а говорит о чем-то внешнем, величины 0.1 и 0.3 никак не принимаются к сведению компилятором.

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

И теперь удивитесь, какие могут быть комментарии к такому простому коду (привел ранее Рыжий Лис):
Вариант 1: высокая точность вычисления не требуется, работает достаточно быстро, поэтому не стал заморачиваться.
Вариант 2: я не знаю, какая точность вычисления требуется; если ракета полетит неточно, то переделайте этот код.
Вариант 3 (комментарий ни о чем): геометрическая сумма
Вариант 4: функция для библиотеки общего назначения (=неизвестной цели использования), вычисления с двойной точностью, при необходимости пользователи могут использовать аналог функции с одинарной точностью.

То есть правильные комментарии не комментируют код, а комментируют обоснование кода, то есть соответствие внешним целям.

0

Что мешает уверенному рефакторингу старого кода? Какой информации не хватает? Есть аналитика на эту тему?

0

Сообщение от Mikhaylo Помимо абстракций неплохо указать явно преобразование целых чисел в Float и обратно.

Тут нет преобразования во флоат, тут целочисленное деление.

Сообщение от Mikhaylo Нужно комментировать внешние системы

Кажется, теперь понимаю, что значит "внешние системы".
В идеале примерно так и получается. Есть комментарии к функциям в заданном формате, а все остальные комментарии относятся к внешней системе. На практике иногда приходится комментировать и код. Такие комментарии желательно помечать специальными тегами (например, todo и note).

Добавлено через 3 минуты

Сообщение от Mikhaylo Что мешает уверенному рефакторингу старого кода? Какой информации не хватает? Есть аналитика на эту тему?

Больше всего мешает отсутствие четкого описания того, что должна делать программа (конкретная часть программы). Приходится заниматься "реверс-инжинирингом".

0