>// Возвращает тестируемый экземпляр Responder.
>protected abstract Responder responderInstance();
Такие комментарии бывают полезными, но там, где это возможно, информацию лучше передавать в имени функции. Например, в данном примере вполне можно обойтись и без комментария — достаточно переименовать функцию в responderBeingTested.
А вот другой, более уместный пример:
>// Поиск по формату: kk:mm:ss EEE, MMM dd, yyyy
>Pattern timeMatcher = Pattern.compile(
> "\\d*:\\d*:\\d* \\w*, \\w* \\d*, \\d*");
На этот раз комментарий сообщает, что регулярное выражение предназначено для идентификации времени и даты, отформатированных функцией SimpleDateFormat.format с заданной форматной строкой. И все же код стал бы лучше (и понятнее), если бы мы переместили этот код в специальный класс, преобразующий форматы даты и времени. Тогда комментарий, вероятно, стал бы излишним.
Иногда комментарий выходит за рамки полезной информации о реализации и описывает намерения, заложенные в решение. В следующем примере мы видим интересный пример архитектурного решения, документированного в комментарии. Автор решил, что при сравнении двух объектов объекты его класса должны находиться в порядке сортировки выше, чем объекты любого другого класса.
>public int compareTo(Object o)
>{
> if(o instanceof WikiPagePath)
> {
> WikiPagePath p = (WikiPagePath) o;
> String compressedName = StringUtil.join(names, "");
> String compressedArgumentName = StringUtil.join(p.names, "");
> return compressedName.compareTo(compressedArgumentName);
> }
> return 1; // Больше, потому что относится к правильному типу.
>}
Или другой, еще лучший пример. Возможно, вы не согласитесь с тем, как программист решает проблему, но по крайней мере вы знаете, что он пытается сделать.
>public void testConcurrentAddWidgets() throws Exception {
> WidgetBuilder widgetBuilder =
> new WidgetBuilder(new Class[]{BoldWidget.class});
> String text = "'''bold text'''";
> ParentWidget parent =
> new BoldWidget(new MockWidgetRoot(), "'''bold text'''");
> AtomicBoolean failFlag = new AtomicBoolean();
> failFlag.set(false);
> // Мы пытаемся спровоцировать "состояние гонки",
> // создавая большое количество программных потоков.
> for (int i = 0; i < 25000; i++) {
> WidgetBuilderThread widgetBuilderThread =
> new WidgetBuilderThread(widgetBuilder, text, parent, failFlag);
> Thread thread = new Thread(widgetBuilderThread);
> thread.start();
> }
> assertEquals(false, failFlag.get());
>}