How to write javadoc

My personal opinion how to write good javadocs (with examples from jdk)

Overview of method/class

Goal of method/class ? What is goal of class. Example:
* The <code>String</code> class represents character strings. All
* string literals in Java programs, such as <code>"abc"</code>, are
* implemented as instances of this class.

Responsibility of method/class ?What method/class is doing. Example in code above.

Action of method ?What statements we can make about how goal is achieved ? Example in StringBuffer class.
/**
* Ensures that the capacity of the buffer is at least equal to the
* specified minimum.
* If the current capacity of this string buffer is less than the
* argument, then a new internal buffer is allocated with greater
* capacity. The new capacity is the larger of:
* <ul>
* <li>The <code>minimumCapacity</code> argument.
* <li>Twice the old capacity, plus <code>2</code>.
* </ul>
* If the <code>minimumCapacity</code> argument is nonpositive, this
* method takes no action and simply returns.
*
* @param minimumCapacity the minimum desired capacity.
*/
public synchronized void ensureCapacity(int minimumCapacity) {
And, of course, describe boundary situations carefully.

Preconditions of method:

Some special agreement then it's legal to apply method/class, example:
* @param s a <code>String</code> containing the <code>int</code>
* representation to be parsed
It's not necessary must be placed in params, but it's good to have such statement. ;)

Postconditions of method:

What it must return if everything is ok.
* @return the integer value represented by the argument in decimal.

Exceptions documentation:

Please don't provide javadoc like "throws Exception if something goes wrong", it has no information in it.
Good Example is:
* @exception NumberFormatException if the string does not contain a
* parsable integer.

CRC description of class

Class javadoc is good then it contains Overview of class, it's responsibilities, classes it coolaborates with, and brief description of working logic and purpose. Example from Timer class.
/**
* A facility for threads to schedule tasks for future execution in a
* background thread. Tasks may be scheduled for one-time execution, or for
* repeated execution at regular intervals.
Examples of use helps a lot sometimes.

Links:

java.sun.com/j2se/javadoc/writingdoccomments/

alistair.cockburn.us/index.php/Structuring_use_cases_with_goals

en.wikipedia.org/wiki/Design_by_contract

Анти паттерны Разаработки через тестирование (TDD Anti-Patterns)

Перевод. Оригинал находится в блоге Джеймса Карра.

Недавно начал набрасывать я документ по анти-паттернам в Разработке - Через - Тестирование, и решил сначала разместить общие паттерны в яху группах.

Обратная реакция оказалась замечательной! В общем, пока это просто каталог, надеюсь он будет расширен со временем.

Каталог Анти-паттернов разработки через тестирование.

Лжец(The Liar)

Тест проходит все свои сценарии и кажется
подтверждает правильную работу класса под тестом, но
если присмотрется получше, он вообще ничего не
тестирует.

Непомерная настройка (Excessive Setup)

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

Гигант (The Giant)

Такой себе тест, которых хотя и тестирует
объект, содержит в себе множество более мелких тестов.
К тому же, он обычно очень длинный и непонятный.
Если у вас появились гиганты, это может означать что
в системе завелись Божественные объекты(англ.).

Симулянт (The Mockery)

Иногда
использование поддельных объектов(mocks) хорошо и удобно. Но
разработчик может переусердствовать, и тест в
результате будет проверять пустышки, поддельные
объекты.

Инспектор (The Inspector)

Юнит тест, который нарушает инкапсуляцию
(сокрытие данных), в попытке достичь 100% покрытия
тестами. Он слишком пристально следит за
внутренностями объекта под тестом, что любая попытка
рефакторинга сломает тест, его или прийдётся
постоянно исправлять.

Ведмежья услуга (Generous Leftovers)

Он оставляет
данные, которые использует другой тест. Если вдруг
порядок поменяется, второй тест не пройдёт.(Да и
понять его с такой услугой будет сложнее).

Местный герой (The Local Hero)

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

Педант (The Nitpicker)

Юнит тест, который сравнивает полный вывод
когда ключевыми являются только его части.
Паразитирует в тестах для сетевых проектов.

Секретный ловец (The Secret Catcher)

Кажется, что он ничего не тестирует
потому, что нет утверждений (assertions), но не зря
говорят "дьявол прячется в деталях". На самом деле
тест проверяет отсуствие исключительных ситуаций в
объекте. Тогда тестирующая система сказала бы об
ошибке.

Халтурщик (The Dodger)

Тест который выполняет проверку мелких эффектов, оставляя в стороне
главную функциональность. Иногда встречается в
тестировании доступа к базе данных, когда тест
проверяет не работу метода у объекта, а правильность
выборки, которую сделал сам.

Крикун (The Loudmouth)

Юнит тест, который забивает консоль
диагностическими сообщениями, логами и прочей ерундой
не смотря на результат исполнения. В процессе
написания теста писали в консоль, и потом удалить
забыли.

Жадный ловец (The Greedy Catcher)

Ловит исключения и проглатывает
информацию о стэке (stack trace). Иногда добавляет
своё сообщение об ошибке, гораздо менее
информативное, иногда просто пишет в лог и идёт тихо
дальше. Противоположность Крикуну.

Аутист (The Sequencer)

Тест, который зависит от последовательности
в непоследовательном списке.

Скрытая зависимость (Hidden Dependency)

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

Нумератор (The Enumerator)

Тестовый класс где методы называются с
помощью цифр. Например: test1, test2, ... В
результате Цель теста непонятна, остаётся только
прочитать тест и молится о понятности кода.

Чужак (The Stranger)

Сценарий тестирования, который даже не
принадлежит тесту, в котором лежит. Обычно, он
тестирует другой объект, тесно связанный с объектом
под тестом. При этом он общается с этим объектом
напрямую, игнорируя базовый объект. Известен ещё как
Дальний родственник.

Проповедник системы (The Operating System Evangelist)

Тест, который надеется на
определённый тип Операционной Cистемы. Как пример,
тест который использует символ новой строки для
Windows, не будет работать под Linux.

Успех вопреки всему (Success Against All Odds)

(я бы назвал Адвокат) Юнит тест,
который написан чтобы срабатывать. Даже когда должен
был бы ломаться.

Свободная езда (The Free Ride)

Вместо нового сценария для теста,
добавляются утверждения в уже существующий сценарий.

Избранный (The One)

Комбинация Гиганта и Свободной езды.
Содержит в себе один сценарий(тестовый метод),
который тестирует всё что делает объект под тестом.
Часто названия теста и метода совпадают, и метод
содержит много строк настройки и утверждений.

Подглядывающий Мальчик (The Peeping Tom)

Тест из-за общих ресурсов
может видеть информацию другого теста и заставить его
провалится даже если система под тестом правильно и
хорошо работает. Часто встречается в Fitnesse, где использование статических переменных с
коллекциями не очищается после выполнения теста,
преподнося сюрпризы. Ещё паттерн известен как
Незванный Гость.

Философ (The Slow Poke)

Юнит тест, который заставляет компьютер
задуматься. Когда его запускаешь, есть время сходить
в ванную, покурить, не вытерпеть и прервать
исполнение в конце рабочего дня.