@Mikhaylo

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

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

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

0

@Shamil1

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

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

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

0

@Mikhaylo

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

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

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

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

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

0

@Mikhaylo

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

0

@Shamil1

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

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

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

0