Собственно назрел такой вопрос, стоит или не стоит добавлять в свой код поясняющие комментарии?
То что код надо писать "красиво" чтобы не только самому потом в нем разобраться этот вопрос  наверно понятен. т.к. грамотно оформленный код признак профессионализма, а вот что по поводу комментариев.
Не как их писать и где, а вообще стоит или нет??? 

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

Была ли у Вас когда-нибудь такая ситуация, что в сделанном Вами проекте через месяц-два понадобилось внести изменения? 
Комментировать код нужно всегда, но это не значит, что надо комментировать каждую строчку, хотя бы только основные блоки (вот здесь у нас приём файлов, здесь авторизация пользователя и т.д.)

И плюс ко всему серьёзные проекты, а так же open-проекты делает (дорабатывает) не один человек. Не каждый сможет сходу понять, что делает Ваш скрипт. Для большинства программистов будет куда проще написать свой собственный такой же скрипт, чем разбираться в не одной сотни строк не прокомментированного кода (это ещё хорошо, если форматирование кода будет читаемым и интуитивно-понятным, что на практике встречается далеко не всегда   ).

А потому комментарии нужны.  

Это сообщение отредактировал(а) HackMan - 19.12.2007, 23:57

ИМХО: однозначно нужны! тут не только играет фактор чтобы люди после тебя смогли понять работу твоих скриптов, главное самому понять через какой то промежуток времени что данный скрипт\участок скрипта делает...

З.Ы. к сожелению я часто коментами пренебригаю   

Ален Голуб в книге "Правила программирования на С и С++" вообще выдвигает идею, что сначала надо писать комментарии, а потом между ними вставлять код. Таким образом, сначала будешь сосредотачиваться на идее алгоритма, и только потом на коде.
Спорно конечно, но что-то в этом есть.

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

как же насчет самодокументирующегося кода ? 
зачем комметировать ф-ю 


итак сразу понятно что она делает. 

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

Это верно. Абсолютно понятные моменты комментировать не нужно. 

Ещё нужно логику комментировать. Т.е. писать не только "открываем файл" и тп, но и для чего вообщем все это написано.

правильно, видел коммент:



а после него еще 50!!! строк кода, и фиг поймешь что там он с ним делает, пока не почитаешь код

для этого лучше делать общее описание модуля, а не лепить все в код.

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

нет. общие описание - это отдельный мануал. Который содержит в себе описание всего проекта, его модулей. Чтобы не сидеть и не рыть тысячи строк кода в поисках ответа на вопрос : "а что же мне эта ф-я возвращает?", а открыть док и посмотреть.

Для этого есть phpdoc, который сам генерит html-мануал исходя из комментариев в коде. Предпочитаю писать небольшое пояснение в заголовке файла, затем прогонять phpdoc и всем, кому интересно кидать ссылку на полученную документацию. Если писать мануалы по проектам, то времени на мануалы тратится больше, чем на кодинг. Я говорю про программистов, которые будут твой код юзать, а не про доку для юзеров, которая с кодом вообще не связана.

Это сообщение отредактировал(а) flashaa - 16.1.2008, 14:59

Зачем, если можно описать, что делает каждая функция в стиле phpDocumentor? Тогда нормальная IDE тебе сама скажет, что делает функция и какие ждет параметры, едва ты наберешь ее имя.