Чистый код. Создание, анализ и рефакторинг

    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());

}

Прояснение

Иногда смысл загадочного аргумента или возвращаемого значения бывает удобно преобразовать в удобочитаемую форму. В общем случае лучше подумать, как сделать так, чтобы этот аргумент или возвращаемое значение говорили сами за себя; но если они являются частью стандартной библиотеки или используются в коде, который вы не можете изменить, то пояснительный комментарий может быть весьма полезным.

public void testCompareTo() throws Exception

{

  WikiPagePath a = PathParser.parse("PageA");

  WikiPagePath ab = PathParser.parse("PageA.PageB");

  WikiPagePath b = PathParser.parse("PageB");

  WikiPagePath aa = PathParser.parse("PageA.PageA");

  WikiPagePath bb = PathParser.parse("PageB.PageB");

  WikiPagePath ba = PathParser.parse("PageB.PageA");

  assertTrue(a.compareTo(a) == 0);    // a == a

  assertTrue(a.compareTo(b) != 0);    // a != b

  assertTrue(ab.compareTo(ab) == 0);  // ab == ab

  assertTrue(a.compareTo(b) == -1);   // a < b

  assertTrue(aa.compareTo(ab) == -1); // aa < ab

  assertTrue(ba.compareTo(bb) == -1); // ba < bb

  assertTrue(b.compareTo(a) == 1);    // b > a

  assertTrue(ab.compareTo(aa) == 1);  // ab > aa

  assertTrue(bb.compareTo(ba) == 1);  // bb > ba

}

Конечно, при этом возникает существенный риск, что пояснительный комментарий окажется неверным. Просмотрите код примера и убедитесь, как трудно проверить его правильность. Это объясняет как необходимость пояснений, так и связанный с ними риск. Итак, прежде чем писать такие комментарии, убедитесь в том, что лучшего способа не существует, и еще внимательнее следите за их правильностью.

Предупреждения о последствиях

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

// Не запускайте, если только не располагаете

// излишками свободного времени.

public void _testWithReallyBigFile()

{

  writeLinesToFile(10000000);

  response.setBody(testFile);

  response.readyToSend(this);

  String responseString = output.toString();

  assertSubString("Content-Length: 1000000000", responseString);

  assertTrue(bytesSent > 1000000000);

}

Конечно, в наше время тестовый сценарий следовало бы отключить при помощи атрибута @Ignore с соответствующей пояснительной строкой: @Ignore("Слишком долго выполняется"). Но до появления JUnit 4 запись с начальным символом подчеркивания перед именем метода считалась стандартной. Комментарий, при всей его несерьезности, хорошо доносит свое сообщение до читателя.

А вот другой, более выразительный пример:

public static SimpleDateFormat makeStandardHttpDateFormat()

{

  // Класс SimpleDateFormat не является потоково-безопасным,