Читаю очень умную книжку - "Чистый код" Роберт Мартин (Robert C. Martin "Clean Code") 2010г.
Пока до половины только прочел...

В предисловии к книге автор допускает, что с его мнениями можно не согласиться. Вот я и не соглашаюсь по одному из них.
На странице 90 (в книжном варианте, иначе 91) автор пишет, про избыточность обязательных комментариев Javadoc (про это там еще где-то написано). И я ни сколько не сомневаюсь в уме этого товарища.
Только он забывает, что по этим комментариям потом можно будет собрать отличное руководство по проекту, в том числе и по классам. О коде-то он позаботился, а что с проектом делать потом, когда все комменты почистить? Люди упрощают создание мануала, понимаешь, а он тут раз и нафиг все.

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

А в php IDE еще и читает эти комментарии и с помощью них восполняет отсутствие строгой типизации в php. К примеру, напишите такое:

/**
* @return UserObject
*/
public function getSomeUsers(){
$userObject = new UserObject();
...
return $userObject;
}
И когда вы будите использовать что-то возвращенное этой функцией, IDE поймет, что вы пользуетесь объектом UserObject!



Ну даже и без этого, все равно можно не согласиться с избыточностью  комментариев.
Вот переменная: duration - Продолжительность воспроизведения в минутах. А как узнать без комментариев в минутах или в часах эта самая продолжительность?
Кстати, если называть durationInMinutes, то это еще тот бред, а если в часах понадобиться, переназывать переменную и свойство класса? так это ж рехнуться можно будет...




PS: кстати у него в коде там ошибка, или не у него, там где он его брал в общем.