Чистый код. Создание, анализ и рефакторинг (Мартин) - страница 52
>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 не является потоково-безопасным,
> // поэтому экземпляры должны создаваться независимо друг от друга.
> SimpleDateFormat df = new SimpleDateFormat("EEE, dd MMM yyyy HH:mm:ss z");
> df.setTimeZone(TimeZone.getTimeZone("GMT"));
> return df;
>}
Возможно, вы возразите, что у задачи есть и более удачные решения. Пожалуй, я соглашусь с вами. Однако комментарий в том виде, в котором он здесь приведен, выглядит абсолютно разумно. По крайней мере он помешает излишне ретивому программисту использовать статический инициализатор по соображениям эффективности.