Форум переехал на новый адрес: http://qsp.su



АвторСообщение





ссылка на сообщение  Отправлено: 10.02.10 15:47. Заголовок: Комментарии к коду - какими они должны быть?


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

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

У меня пока все сводится к общему обозначению того что делает каждая локация, ну и в лучшем случае еще объяснение того за какое действие отвечают некоторые куски кода.

Может посоветуете хорошие статьи, примеры или просто дадите совет?

Спасибо: 0 
Профиль Цитата Ответить
Ответов - 23 , стр: 1 2 All [только новые]


moderator


ссылка на сообщение  Отправлено: 10.02.10 16:07. Заголовок: MasterSet пиши то, ч..


MasterSet пиши то, что пишется само собой - это и будет самым уместным комментарием.


 цитата:
пока все сводится к общему обозначению того что делает каждая локация, ну и в лучшем случае еще объяснение того за какое действие отвечают некоторые куски кода


Вот это и пиши.

Спасибо: 0 
Профиль Цитата Ответить





ссылка на сообщение  Отправлено: 10.02.10 17:02. Заголовок: Сами собой каменты н..


Сами собой каменты не идут. Приходится себе напоминать.

Спасибо: 0 
Профиль Цитата Ответить





ссылка на сообщение  Отправлено: 10.02.10 17:11. Заголовок: Я обычно делаю так: ..


Я обычно делаю так: все важные переменные описываю в отдельной локации start, а при запуске игры просто делаю gs 'start', чтобы все эти переменные приняли свои начальные значения, описываю все, даже если они изначально равны нулю. И тут же делаю описание, что это такое, т.е. я в любой момент могу зайти в эти локацию и посмотреть.


 цитата:
например
! деньги главное героя
m=100
! опыт главного героя
op=0
...
и т.д.



А в самой игре стараюсь всё происходящее разбивать на логические блоки кода и к каждому просто пишу что он делает.

Спасибо: 0 
Профиль Цитата Ответить
администратор




ссылка на сообщение  Отправлено: 10.02.10 17:40. Заголовок: Важно помнить, что д..


Важно помнить, что для понятного кода комментарии излишни :)
Например, одно-двухбуквенные переменные лучше не использовать - "деньги" или "money" намного лучше, чем "m".
Исключением могут быть разве что временные переменные, значение которых важно только в текущем куске кода.

Спасибо: 0 
Профиль Цитата Ответить
moderator


ссылка на сообщение  Отправлено: 10.02.10 17:56. Заголовок: Byte отлично сказал...


Byte отлично сказал.

Спасибо: 0 
Профиль Цитата Ответить





ссылка на сообщение  Отправлено: 10.02.10 18:17. Заголовок: Ну с этим как раз по..


Ну с этим как раз порядок. Я называю переменные максимально подходящими названиями, так что мне не приходится специально их вспоминать, даже если я вернулся к коду после перерыва.
Это не только потом помогает, но и прямо в процессе работы.

Спасибо: 0 
Профиль Цитата Ответить
демиург




ссылка на сообщение  Отправлено: 10.02.10 19:25. Заголовок: Одно время пыталась ..


Одно время пыталась писать коменты, а потом плюнула. Сейчас делаю это только при необходимости разграничения кода. Если в локации только код, то локация как правило имеет говорящее название о том что этот код делает. Поэтому вот.

Спасибо: 0 
Профиль Цитата Ответить





ссылка на сообщение  Отправлено: 10.02.10 20:00. Заголовок: Ясно. Силы лени побе..


Ясно.
Силы лени победили силы бобра даже среди небожителей. Сопротивление бесполезно.
Будем плыть по течению и забьем на каменты

Спасибо: 0 
Профиль Цитата Ответить





ссылка на сообщение  Отправлено: 10.02.10 20:32. Заголовок: Byte пишет: Важно п..


Byte пишет:

 цитата:
Важно помнить, что для понятного кода комментарии излишни :)
Например, одно-двухбуквенные переменные лучше не использовать - "деньги" или "money" намного лучше, чем "m".
Исключением могут быть разве что временные переменные, значение которых важно только в текущем куске кода.



Почему же? По-моему как раз наоборот. важные переменные лучше делать однобуквенными.
Причина проста: какого вероятность, что ты опечатаешься в слове "м"? а в слове "money"?

Спасибо: 0 
Профиль Цитата Ответить





ссылка на сообщение  Отправлено: 10.02.10 20:35. Заголовок: Одно-двубуквенные пе..


Одно-двубуквенные переменные лично мне совершенно не удобны.

Спасибо: 0 
Профиль Цитата Ответить
moderator




ссылка на сообщение  Отправлено: 26.02.10 14:42. Заголовок: ИМХО Комментарии ста..


ИМХО
Комментарии ставить обязательно :) для переменных и условий.

! деньги главное героя
money=100
...
! ГГ нашел 100р
money=money + 100

...
! у ГГ отобрали 100р
if gopniki = 1: money=money - 100

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

Спасибо: 0 
Профиль Цитата Ответить
демиург




ссылка на сообщение  Отправлено: 26.02.10 16:26. Заголовок: HIman Ну, мне кажетс..


HIman Ну, мне кажется, в твоём куске и без коментов было бы всё понятно. :)
Особенно если знать, что главный герой один и деньги водятся только у него. :)

Спасибо: 0 
Профиль Цитата Ответить





ссылка на сообщение  Отправлено: 26.02.10 16:37. Заголовок: HIman Помоему это ре..


HIman Помоему это реально жесть - если так подробно комментировать даже такие тривиальные куски, то код вырастет вдвое.

Спасибо: 0 
Профиль Цитата Ответить
moderator




ссылка на сообщение  Отправлено: 26.02.10 16:58. Заголовок: Вот когда переменная..


Вот когда переменная примет в очередной локации значение vbr1=115
и на момент написание кода вам кристально ясно почему это произошло
(как впрочем и vbr1=vbr1+115),
то через n-ое количество времени голову будите ломать и шерстить код куда больше, чтобы понять почему в очередной локации эта переменная именно этим значением присваивалась.

С IF ещё тривиальнее, так как накладывается здесь ещё логические условия на код.

Спасибо: 0 
Профиль Цитата Ответить





ссылка на сообщение  Отправлено: 26.02.10 17:04. Заголовок: У меня до сих пор та..


У меня до сих пор такой беды с переменными не наблюдалось, хотя за полмегабайта кода было.
Все-таки тупо комментить все подряд... это тупо ИМХО )

HIman пишет:

 цитата:
С IF ещё тривиальнее, так как накладывается здесь ещё логические условия на код.



А эту фразу можно пояснить? Ее смысл от меня упорно ускользает.

Спасибо: 0 
Профиль Цитата Ответить
moderator




ссылка на сообщение  Отправлено: 26.02.10 17:28. Заголовок: На данный момент я +..


На данный момент я + сценарист пишем игру,
сценарист привыкает к новому графическому подходу структурировать свои мысли через граф,
я привыкаю к новому автоматному программированию.

Из такого подхода и вытекают необходимости:
1. коментарить переменные так как их может насчитываться несколько сотен на игру.
2. коментарить IFы (или в мое случае блоки кода) так как удобно скрывать в редакторе содержимое блока IF END и ориентироваться на комментарий написанный строкой выше. На одну локацию может от 2 до десятков таких вот блоков.

Спасибо: 0 
Профиль Цитата Ответить





ссылка на сообщение  Отправлено: 26.02.10 17:57. Заголовок: Теперь понятно. При ..


Теперь понятно. При таком подходе это очевидно оправдано, но надо было сразу это пояснить.
Я к примеру пишу все один, без всяких графов и мне такое ни к чему.

Трудозатраты выходят значительно меньше и не надо коментить все подряд.

Спасибо: 0 
Профиль Цитата Ответить





ссылка на сообщение  Отправлено: 26.02.10 23:08. Заголовок: HIman Поделись инстр..


HIman Поделись инструментом, на котором рисуете графы?

Спасибо: 0 
Профиль Цитата Ответить





ссылка на сообщение  Отправлено: 26.02.10 23:40. Заголовок: Ватман, полюбому )..


Ватман, полюбому )

Спасибо: 0 
Профиль Цитата Ответить
демиург




ссылка на сообщение  Отправлено: 26.02.10 23:43. Заголовок: MasterSet пишет: В..


MasterSet пишет:

 цитата:

Ватман, полюбому )



Вряд ли.

Спасибо: 0 
Профиль Цитата Ответить
Ответов - 23 , стр: 1 2 All [только новые]
Ответ:
1 2 3 4 5 6 7 8 9
большой шрифт малый шрифт надстрочный подстрочный заголовок большой заголовок видео с youtube.com картинка из интернета картинка с компьютера ссылка файл с компьютера русская клавиатура транслитератор  цитата  кавычки моноширинный шрифт моноширинный шрифт горизонтальная линия отступ точка LI бегущая строка оффтопик свернутый текст

показывать это сообщение только модераторам
не делать ссылки активными
Имя, пароль:      зарегистрироваться    
Тему читают:
- участник сейчас на форуме
- участник вне форума
Все даты в формате GMT  3 час. Хитов сегодня: 6
Права: смайлы да, картинки да, шрифты да, голосования нет
аватары да, автозамена ссылок вкл, премодерация вкл, правка нет



Создай свой форум на сервисе Borda.ru
Текстовая версия