Документация с комментариями
Введено| English | Значение |
|---|---|
| comment/ˈkɒment/ | комментарий |
Комментарий не исправляет активную формулу
- Для цены 100 выражение
total = price * 10 / 100;вычисляет значение 10, даже если комментарий гласит «сумма к оплате после десятипроцентной скидки». Редактирование этого пояснения не заставит выражение вычислять значение 90. - Измените активное выражение на
price * 90 / 100, чтобы вычислить предполагаемую сумму оплаты в этом примере с целыми числами. Комментарии могут раскрыть задуманную политику; убедитесь, что код реализует её.
Определите текст, исключаемый из кода
//начинает однострочный комментарий до конца строки./*начинает блочный комментарий до следующего*/; блочные комментарии не вкладываются друг в друга. Разделители внутри строковых литералов являются текстом, поэтому"https://example.com"не начинает комментарий.- Текст комментария не исполняется как операторы Java. Добавление отдельного пояснения не изменяет активное выражение; размещение
//перед активным присваиванием исключает это присваивание из скомпилированного кода и может изменить поведение программы.
Размещайте теги Javadoc на отдельных строках
- Документационный комментарий
/** ... */непосредственно перед объявлением может быть обработан утилитой Javadoc. Его сводка объясняет работу метода; блочные теги, такие как@paramи@return, начинаются на собственных строках после optional whitespace и*. - Приведенный ниже полный класс документирует неотрицательный радиус и возвращает площадь круга. Теги описывают входные данные, выходные данные и отвергнутый вход; сам по себе комментарий не обеспечивает выполнение предварительного условия, поэтому метод явно проверяет отрицательные радиусы.
/** Circle-area calculations for finite radii. */
public class AreaDoc {
/**
* Returns the area of a circle for a finite radius.
* @param r the non-negative radius
* @return the area in squared radius units
* @throws IllegalArgumentException if r is negative
*/
public static double area(double r) {
if (r < 0) {
throw new IllegalArgumentException("Negative radius");
}
return Math.PI * r * r;
}
}
Javadoc распознает @param как блочный тег, когда он встроен после текста сводки в той же строке.
Сложность 1/5 · 100 монет + небольшой бонус за первое выполнение сегодня
Блочный тег начинается с новой строки после optional whitespace и опциональной ведущей звездочки. Используйте показанный многострочный комментарий.
Объясните решение, которое читатель не видит
- Полезный комментарий о скидке может гласить: «оплата составляет 90% от указанной цены; в этом упражнении используются цены в целых числах». Это объясняет политику и предположения, в то время как
// multiply by 90лишь повторяет операцию. - Сводка публичного метода полезна даже тогда, когда ее тело короткое: вызывающему коду нужен контракт без изучения реализации. Предпочтительны объяснения, которые восполняют отсутствующий контекст, а не утверждения о том, что каждый описательный комментарий избыточен.
Когда программа Java выполняется, комментарии...
Сложность 1/5 · 100 монет + небольшой бонус за первое выполнение сегодня
Комментарии предназначены для людей — Java игнорирует их.
Что начинает однострочный комментарий в Java?
Сложность 1/5 · 100 монет + небольшой бонус за первое выполнение сегодня
// продолжается до конца строки; /* */ — это блочный комментарий.
Какой стиль комментариев инструменты превращают в документацию API?
Сложность 1/5 · 100 монет + небольшой бонус за первое выполнение сегодня
Javadoc /** */ с @param/@return генерирует документацию API.
Добавление поясняющего комментария рядом с неизмененной активной формулой исправляет её вычисление.
Сложность 1/5 · 100 монет + небольшой бонус за первое выполнение сегодня
Неверно: поясняющие комментарии не являются операторами. Закомментирование оператора может изменить поведение, но это изменяет только то, какой код является активным.
Хорошие комментарии объясняют ЗАЧЕМ, а не повторяют, что код явно делает.
Сложность 1/5 · 100 монет + небольшой бонус за первое выполнение сегодня
Комментируйте намерения, а не очевидное.
Проверяйте документацию на соответствие реализации
- Предположим, комментарий обещает отклонение отрицательных радиусов, но проверка (guard) удалена. Документация теперь неверна, хотя код всё ещё компилируется успешно; протестируйте как отрицательный входной параметр, так и обычный радиус.
- При изменении поведения обновляйте реализацию, её проверки и документацию одновременно. Генерация страницы API проверяет синтаксис документации, а не истинность каждого утверждения в ней.
/** Returns an area. @param r radius @return area */ не размещает тегі block-комментариев в начале требуемых строк. Используйте многострочную форму выше, затем проверьте сгенерированные разделы параметров и возвращаемых значений. Обычные поясняющие комментарии не являются исполняемыми исправлениями.
Полезный комментарий или нет?
Хорошие комментарии объясняют намерения, а не очевидное. Отсортируйте каждый из них.
Предскажите закомментированное присваивание
- Начните со
int x = 1;. При активномx = 5;вывод x даст 5; замена этой строки на// x = 5;выведет 1. Изменение того, какие операторы активны, отличается от добавления примечания рядом с неизменным оператором. - Рассмотрите три вопроса отдельно: верен ли активный расчёт, точно ли объясняет его комментарий и распаршены ли Javadoc-теги в нужные разделы? Успешная компиляция не отвечает на все три вопроса.
Комментарии объясняют код читателям. Разделители могут исключать операторы, тогда как заметки рядом с активным кодом не исправляют ошибки в расчётах. Tegi block-комментариев Javadoc начинаются с отдельных строк; поддерживайте согласованность задокументированного контракта с реализацией.
For a price of 100, type the amount paid after a ten percent discount.
Сложность 1/5 · 100 монет + небольшой бонус за первое выполнение сегодня
The intended payment is 100−10=90. The misleading comment does not make the original expression calculate 90.
int x = 1; за этим следует // x = 5; в отдельной строке. Какое значение x будет выведено?
Сложность 2/5 · 140 монет + небольшой бонус за первое выполнение сегодня
Присваивание 5 исключается однострочным комментарием; x остается равным 1.