| Версия для печати темы
Нажмите сюда для просмотра этой темы в оригинальном формате |
| Форум программистов > PHP: Общие вопросы > Вопрос по оформлению кода |
| Автор: SDEVIL 19.12.2007, 19:45 |
| Собственно назрел такой вопрос, стоит или не стоит добавлять в свой код поясняющие комментарии? То что код надо писать "красиво" чтобы не только самому потом в нем разобраться этот вопрос наверно понятен. т.к. грамотно оформленный код признак профессионализма, а вот что по поводу комментариев. Не как их писать и где, а вообще стоит или нет??? |
| Автор: Anarki 19.12.2007, 20:15 |
| Стоит, сам же если будешь потом просматривать скрипт через какой-то длительный промежуток времени, будет проще понять что писал. |
| Автор: HackMan 19.12.2007, 23:51 |
| Была ли у Вас когда-нибудь такая ситуация, что в сделанном Вами проекте через месяц-два понадобилось внести изменения? Комментировать код нужно всегда, но это не значит, что надо комментировать каждую строчку, хотя бы только основные блоки (вот здесь у нас приём файлов, здесь авторизация пользователя и т.д.) И плюс ко всему серьёзные проекты, а так же open-проекты делает (дорабатывает) не один человек. Не каждый сможет сходу понять, что делает Ваш скрипт. Для большинства программистов будет куда проще написать свой собственный такой же скрипт, чем разбираться в не одной сотни строк не прокомментированного кода (это ещё хорошо, если форматирование кода будет читаемым и интуитивно-понятным, что на практике встречается далеко не всегда А потому комментарии нужны. |
| Автор: MoLeX 20.12.2007, 07:33 |
| ИМХО: однозначно нужны! тут не только играет фактор чтобы люди после тебя смогли понять работу твоих скриптов, главное самому понять через какой то промежуток времени что данный скрипт\участок скрипта делает... З.Ы. к сожелению я часто коментами пренебригаю |
| Автор: N0dwis 20.12.2007, 09:01 |
| Ален Голуб в книге "Правила программирования на С и С++" вообще выдвигает идею, что сначала надо писать комментарии, а потом между ними вставлять код. Таким образом, сначала будешь сосредотачиваться на идее алгоритма, и только потом на коде. Спорно конечно, но что-то в этом есть. |
| Автор: DrWeb 23.12.2007, 00:31 |
| безусловно комменты нужны.когда будешь просматривать код проги,то можешь забыть за что отвечает та или иная перменная,цикл,функция и т.п.Конечно если у тебя феноменальная память,то..лучше подстраховаться,все случается |
| Автор: mikla 15.1.2008, 12:53 | ||
| как же насчет самодокументирующегося кода ? зачем комметировать ф-ю
итак сразу понятно что она делает. я считаю, что документировать нужно только тонкие моменты. Излишние комментарии нагружают код. |
| Автор: FractalizeR 16.1.2008, 01:12 | ||
Это верно. Абсолютно понятные моменты комментировать не нужно. |
| Автор: flashaa 16.1.2008, 13:37 |
| Ещё нужно логику комментировать. Т.е. писать не только "открываем файл" и тп, но и для чего вообщем все это написано. |
| Автор: mikla 16.1.2008, 14:05 | ||
для этого лучше делать общее описание модуля, а не лепить все в код. |
| Автор: flashaa 16.1.2008, 14:14 | ||
А общее описание модуля где находится? Или имелось в виду, писать в заголовок файла? Если так, то в заголовке обычно пишут, как надо использовать модуль, а внутреннее устройство как раз внутри кода - над каждым интересующим куском кода пишем, какова его логика. Вообще я имел в виду то, что в коментах надо раскрывать именно логику вместо тупого пояснения работы операторов, т.к. про операторы и тп можно посмотреть в мануале, а что хотел сделать автор модуля мы кроме как из комментов ниоткуда не узнаем. И код сильно не расширится, если вместо "открываем файл" писать "из файла берем данные для отображения такого-то раздела". |
| Автор: mikla 16.1.2008, 14:53 | ||
нет. общие описание - это отдельный мануал. Который содержит в себе описание всего проекта, его модулей. Чтобы не сидеть и не рыть тысячи строк кода в поисках ответа на вопрос : "а что же мне эта ф-я возвращает?", а открыть док и посмотреть. |
| Автор: flashaa 16.1.2008, 14:56 | ||
Для этого есть phpdoc, который сам генерит html-мануал исходя из комментариев в коде. Предпочитаю писать небольшое пояснение в заголовке файла, затем прогонять phpdoc и всем, кому интересно кидать ссылку на полученную документацию. Если писать мануалы по проектам, то времени на мануалы тратится больше, чем на кодинг. Я говорю про программистов, которые будут твой код юзать, а не про доку для юзеров, которая с кодом вообще не связана. |
| Автор: FractalizeR 16.1.2008, 15:00 |
| Зачем, если можно описать, что делает каждая функция в стиле phpDocumentor? Тогда нормальная IDE тебе сама скажет, что делает функция и какие ждет параметры, едва ты наберешь ее имя. |
| Автор: MoLeX 16.1.2008, 15:09 |
а ссылку моно на него? |
| Автор: flashaa 16.1.2008, 15:21 |
http://www.phpdoc.org/ |