Зачем дьявол придумал javadoc

Есть мнение, что хорошая программа должна быть хорошо задокументирована.

Компания SUN даже придумала специальный формат javadoc — «стандарт для документирования классов Java». В моей практике было совершенно обычным явлением, когда какой-то код не проходил Code Review, потому что в нём у некоторых методов отсутствовали комментарии.

Я утверждаю, что этот подход устарел, и сегодня я расскажу, почему комментарии — это зло.

Пример из жизни

Это реальный код, написанный в 2010 году вполне старательным программистом, который не поленился и написал комментарий к своему методу. Довольный собой, но пошёл налить себе чашечку кофе из аппарата, а мы давайте-ка пока посмотрим, что же тут у нас есть.

public class AddressUtil {
/**
* Format string as address, expected input
* format:"EE ; ;Tallinn;Narva mnt;120B;831;10127"
*
* @param flatAddress
* @return Formatted address
*/
public static String toString(String flatAddress) {......}
}

Отлично! У нас есть корректно оформленный комментарий в формате javadoc, из которого специальная программа сможет сгенерировать HTML-документацию. По нему легко можно понять, что (теоретически) делает этот метод.

Где же спрятался дьявол?

Но где же те мелочи, в которых спрятался дьявол? А вот они:

• Очень скоро эта документация устареет, потому что придёт другой девелопер и поменяет код, но забудет поменять документацию. Это может быть даже тот же самый девелопер, потому что пока он стоял в очереди за кофе, ему пришло в голову, что он забыл обработать один редкий случай. Вернувшись, он добавит нужный IF в код, но забудет о том, что у него уже есть javadoc, который необходимо поддерживать.
• В документации не описаны масса случаев: как поведёт себя метод, если на входе придёт null или пустая строка? Что, если в адресе есть номер дома, но нет номера квартиры (то есть буржуй занял дом целиком)? Что там за пустой параметр между «EE» и «Tallinn»?
• В документации нет ни слова о том, что этот метод возвращает.
• В документации есть целых три лишних строчки: "*", "@param flatAddress" и "@return Formatted address". Только подумайте: они занимают большую часть документации, и они абсолютно бесполезны!

Волшебство

А теперь давайте поиграем в волшебников и превратим несколько цветных кусочков в гирлянду. Сделаем несколько магических пассов. Сим-салябим, Ахалай-махалай, Ляськи-масяськи…

• Пасс номер 1: Всё, что написано красным цветом, превращаем в название метода: toString -> formatAddress.
• Пасс номер 2: Всё, что написано синим цветом, переносим в юнит-тест.
• Пасс номер 3: (мой любимый) Весь текст, написанный зелёным цветом — … правильно, стираем. Навсегда. Не жалейте его, он зря появился на свет!

Что у нас получилось в итоге?

public class AddressUtil {
public static String formatAddress(String flatAddress) {......}

@Test public void testFormatAddress() {
assertEquals("Narva mnt 120B-831 10127 Tallinn",
AddressUtil.formatAddress("EE ; ;Tallinn;Narva mnt;120B;831;10127"));
}

}

Чем же новый вариант лучше старого?

• Он тупо КОРОЧЕ: было 8 строк, стало 4.
• Этот тест никогда не устареет, т.к. он будет запускаться автоматически каждый раз при сборке проекта, и если программист поменяет код, а о методе забудет, это сразу всплывёт.
• Можно описать все редкие случаи: пустые строки, отсутствующие параметры, недопустимые значения и т.д.

Одним словом,

ХОРОШЕЕ НАЗВАНИЕ + ТЕСТЫ = ДОКУМЕНТАЦИЯ

а точнее, «запускаемая документация» (executable documentation), то есть документация, которую можно не просто читать, но ещё и «запускать», автоматически проверяя, что она всё ещё адекватна.

Говорят, у Конфуция над кроватью висел плакат:

Convert comments to executable documentation

Послесловие

Боюсь только, что наш доблестный программист, вернувшись с кухни, фокуса не поймёт, ведь он не видел наших волшебных движений. Ему снесёт башню от одного только факта, что его комментарии КТО-ТО НАГЛО ПОТЁР, и он постарается нас найти и уничтожить за такую подрывную деятельность. А его кофе тем временем остынет. Ну что ж, и то неплохо: ведь кофе, говорят, вреден. Значит, одно хорошее дело мы всё-таки сегодня сделали.



UPDATE
В комментариях посыпалась куча возмущений по поводу того, что неудобно использовать open-source библиотеки без документации. Эта статься не о коде, идущем на экспорт. Она о «внутреннем» коде, который пишите вы и ваши коллеги, и использовать будете только вы и ваши коллеги, и который вам предстоит ещё менять неоднократно. В «экспортном» коде всё по-другому — там документация безусловно нужна, но за её за состоянием требуется отдельно следить. Её вам не потребуется менять, а только читать. Это совсем другая история.


Андрей Солнцев