Всегда приятно читать хорошо оформленный и документированный код. Его не только в разы проще читать и понимать, но и на него просто приятно смотреть. Как правило, начинающие программисты леняться документировать свой код в силу тех или иных причин. Сам раньше не документировал. Но после того как пришлось разбираться в чужом сложном и не документированном коде понял, что не документировать код - это страшный эгоизм и издевательство над своими коллегами. Вот будет кто - то читать мой код, когда я с ним уже закончу, и будет громко произносить в мой адрес страшные эпитеты. Поэтому теперь я стараюсь документировать свой код как можно тщательнее. Тем более, что не задокументировав код и вернувшись к нему через некоторое время, опять придется в нем разбираться, потому что уже все забыл.
Одной из преград к документированию кода для меня было то, что я не знал как это правильно делать. Но тут меня выручил замечательный стандарт Docblock. В нем описывается как надо правильно писать комментарии к коду, чтобы он был не только легко читаем человеком, но и понимался различными IDE для формирования всплывающих подсказок.