Версия для печати темы
Нажмите сюда для просмотра этой темы в оригинальном формате
Форум программистов > PHP: Общие вопросы > Вопрос по оформлению кода


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

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

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

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

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

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

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

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

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

Автор: mikla 15.1.2008, 12:53
как же насчет самодокументирующегося кода ? 
зачем комметировать ф-ю 
Код

function db_connect () 


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

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

Автор: FractalizeR 16.1.2008, 01:12
Цитата(mikla @ 15.1.2008,  12:53)
я считаю, что документировать нужно только тонкие моменты.  Излишние комментарии нагружают код.

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

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

Автор: MoLeX 16.1.2008, 13:44
Цитата(flashaa @  16.1.2008,  13:37 Найти цитируемый пост)
Ещё нужно логику комментировать. Т.е. писать не только "открываем файл" и тп, но и для чего вообщем все это написано.

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

Код

//открываем файл и начинаем с ним чтото делать


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

Автор: mikla 16.1.2008, 14:05
Цитата(flashaa @ 16.1.2008,  13:37)
Ещё нужно логику комментировать. Т.е. писать не только "открываем файл" и тп, но и для чего вообщем все это написано.

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

Автор: flashaa 16.1.2008, 14:14
Цитата(mikla @  16.1.2008,  14:05 Найти цитируемый пост)
для этого лучше делать общее описание модуля, а не лепить все в код. 

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

Автор: mikla 16.1.2008, 14:53
Цитата(flashaa @ 16.1.2008,  14:14)
А общее описание модуля где находится? Или имелось в виду, писать в заголовок файла?

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

Автор: flashaa 16.1.2008, 14:56
Цитата(mikla @  16.1.2008,  14:53 Найти цитируемый пост)
Чтобы не сидеть и не рыть тысячи строк кода в поисках ответа на вопрос : "а что же мне эта ф-я возвращает?"

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

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

Автор: MoLeX 16.1.2008, 15:09
Цитата(flashaa @  16.1.2008,  14:56 Найти цитируемый пост)
phpdoc

а ссылку моно на него?

Автор: flashaa 16.1.2008, 15:21
Цитата(MoLeX @  16.1.2008,  15:09 Найти цитируемый пост)
а ссылку моно на него? 

http://www.phpdoc.org/

Powered by Invision Power Board (http://www.invisionboard.com)
© Invision Power Services (http://www.invisionpower.com)