>* 29.05.2003 : Исправление ошибки в методе addMonths (DG);
>* 04.09.2003 : Реализация Comparable. Обновление isInRange javadocs (DG);
>* 05.01.2005 : Исправление ошибки в методе addYears() (1096282) (DG);
Когда-то создание и сопровождение журнальных записей в начале каждого модуля было оправдано. У нас еще не было систем управления исходным кодом, которые делали это за нас. В наши дни длинные журналы только загромождают и усложняют код. Их следует полностью удалить из ваших программ.
Также в программах нередко встречаются комментарии, не содержащие ничего, кроме «шума». Они лишь утверждают очевидное, не предоставляя никакой новой информации.
>/**
>* Конструктор по умолчанию.
>*/
>protected AnnualDateRule() {
>}
Да неужели? А как насчет этого:
>/** День месяца. */
> private int dayOfMonth;
И наконец, апофеоз избыточности:
>/**
>* Возвращает день месяца.
>*
>* @return день месяца.
>*/
>public int getDayOfMonth() {
> return dayOfMonth;
>}
Эти комментарии настолько бесполезны, что мы учимся не обращать на них внимания. В процессе чтения кода наш взгляд просто скользит мимо них. Рано или поздно код вокруг таких комментариев изменяется, и они начинают лгать.
Первый комментарий в листинге 4.4 кажется уместным. Он объясняет, почему блок catch игнорируется. Но второй комментарий не несет полезной информации. Видимо, программист настолько вышел из себя при написании этих блоков try/catch в этой функции, что ему понадобилось «выпустить пар».
Листинг 4.4. startSending
>private void startSending()
>{
> try
> {
> doSending();
> }
> catch(SocketException e)
> {
> // Нормально. Кто-то прервал запрос.
> }
> catch(Exception e)
> {
> try
> {
> response.add(ErrorResponder.makeExceptionString(e));
> response.closeAll();
> }
> catch(Exception e1)
> {
> // Ну хватит уже!
> }
> }
>}
Вместо того чтобы давать выход чувствам в бесполезном комментарии, программисту следовало понять, что раздражение можно было снять улучшением структуры кода. Ему стоило направить свою энергию на выделение последнего блока try/catch в отдельную функцию, как показано в листинге 4.5.
Листинг 4.5. startSending (переработанная версия)
>private void startSending()
>{
> try
> {
> doSending();
> }
> catch(SocketException e)
> {
> // Нормально. Кто-то прервал запрос.
> }
> catch(Exception e)
> {
> addExceptionAndCloseResponse(e);
> }
>}
>private void addExceptionAndCloseResponse(Exception e)
>{
> try
> {
> response.add(ErrorResponder.makeExceptionString(e));
> response.closeAll();
> }
> catch(Exception e1)
> {
> }
>}
Искушение создать очередной «шумовой комментарий» следует заменить решимостью очистить код. Вы сами увидите, что это сделает вашу работу более приятной и эффективной.