Etherlords/reality-0.1 — Issue #2: Коментирование кода
Author: gNikro
Created: 2012-01-31 10:53:22+00:00
State: open

Предлагаю следующие правила завести

1. Все поля класса коментируются
Простое поле коментируется кратким изяснением

//Количество букв а в слове
private var a:Number

метод коментируется метатегами более развернуто
Изъяснение метода(что он делает)

Входные значение, каждый парамтер описывается

Выходное значение, что и зачем поулчили

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

так же коментарий к классу какую работу выполняет он

2. Желательны разяснения внутри метода типа что вот в этой операции мы сделали

//Просто для теста установил координаты 100х100
body.x = 100;
body.y = 100;

или даже лучше
//@FORDEL
что то типо таго чтобы знать что это в итоге нужно убрать

Или же просто разясняющий коментарий

//Вызываем рендер чтобы синхронизировать представление и скин
render();

Так будет проще понимать код, а в итоге можно будет патом избавлятся потихоьнку от этих коментов

3. Вот мы пишем пишем код и в какой то момент видим что вот тут не плохо бы сделать такую то штуку но сейчас на это времени нету

И мы напишем комент побыстрому

/*
@какой нибудь тег например @architect
@author gNikro
................
Фактически наследник этого объекта, или некий контроллер работающий с этим объектом будет уже реализовывать логику конкретной сущьности
Если это кролик, то реализуем там логику управления его скином(анимациями), прыжки кролика и тд.
*/

тоесть это рекомендации или советы по архитектуре когда они будут заимплементены или учтены или вычеркнуты их можно будет удалять. А мы в какой то момент сможем по ним просто пробежаться про анализировать или по ходу реализации учесть

Если есть еще пожелания то.....?