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

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

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

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

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

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

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

цитата:

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

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

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

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

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

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

цитата:

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

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

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

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

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

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

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

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

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

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

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

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

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

Byte пишет:

цитата:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

HIman пишет:

цитата:

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

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

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

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

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

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

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

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

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

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

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

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

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

MasterSet пишет:

цитата:

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

Вряд ли.