ссылки для программистов

[avva]

Эта запись будет интересна только программистам.

1. (специально для веб-разработчиков) Прекрасная чашка:



2. Отличная подборка на stackoverflow: What is the best comment in source code you have ever encountered?.

Много хорошего (см. также комментарии на реддит). Отмечу такие шедевры, как

1. try {

} finally { // should never happen

}

2. return 1; # returns 1

3. // I'm sorry.

4. вот этот

Comments

[vladimirgin.livejournal.com]

Ну, я не пишу на java, поэтому javadoc не актуально. Насчет "Код должен быть понятен без комментов" в принципе соглашусь, если это не подразумевает, что надо отказаться от комментов как класса. Зачастую они необходимы. Хотя бы для того, чтобы дать понять, как именно этот кусок кода связан с предметной областью.

[javax-slr.livejournal.com]

Комменты для public API
Комменты для сложных алгоритмов и вычислений
Комменты в условиях
if (parent == null) { // happens for empty data sets

В других местах если хорошие имена переменных и методов - редко нужно

[vladimirgin.livejournal.com]

К этому нет вопросов, примерно такую же policy и я применяю.

[dimrub.livejournal.com]

> Ну, я не пишу на java, поэтому javadoc не актуально.

RTFM: Doxygen.