Ru:Code guide
Материал из Pocket Fallout для КПК на PDA PC PPC Mobile.
Правила оформления кода скриптов
Содержание |
Для чего необходимы эти правила
Эти правила необходимы для стандартизации стиля написания кода. Для того что бы :
- Вы сами могли читать код своей программы (даже если Вы в нее не заглядывали месяцами).
- Быстро ориентироваться, что делает тот или иной кусок программы при этом не в вдумываясь в логику операторов.
- Что бы сторонний разработчик мог «прочитать» Вашу программу (например в целях дополнения функционала или исправления каких либо ошибок).
Данные правила включают в себя классические элементы оформления кода, взятые с различных языков. Очень рекомендуется придерживаться ниже описанных правил, при написании скриптов.
- Учитесь писать код по этим правилам сразу, не откладывайте на "потом". Это поможет Вам приучить себя к правильному стилю написания программ.
- Проверяйте сами себя, учитесь читать свой код, не полагайтесь на отладчики, т.к. прочитав свой код вы быстрее найдете ошибку и научите себя не делать ее в дальнейшем.
- Написали кусок модуля - пробежитесь по нему глазами, почитайте, что Вы написали, посмотрите как оформили. Всегда рассчитывайте на то, что Ваш код будут смотреть и другие люди. Облегчите им понимание вашего труда, и эти люди будут Вам благодарны. Представляйте, что Вы - не автор, а человек впервые увидевший вашу работу.
- Код должен быть само-документирован, т.е. все идентификаторы должны иметь понятные имена. Имя должно само говорить за себя, что делает, что хранит и т.п. Однако это правило не исключает наличие комментариев.
- Комментарии должны быть, но не "перебарщивайте" с ними. Стремитесь "читабельному" коду с к коротким и понятным комментариям, как например :
//функция рассчитывает вероятность возникновения боя function mCalculateFightProbability()
Изначально, Вам будет тяжело, т.к. в школах/университетах этому не учат, но как только Вы ощутите прелесть быстрого вникания в суть кода, без чтения его операторной последовательности, Вам даже понравиться именно так писать свой код !
Оформление текста кода
1. Ключевые операторы пишутся в нижнем регистре
Неправильно :
Procedure, If, Then, And
Правильно :
procedure, if, then, and и т.п.
2. Завешенные логические выражения, преимущественно в условиях, брать в скобки.
Неправильно :
if a==b and c==b then
Правильно :
if (a==b) and (c==b) then
Совет : Если в Вашем коде большое по логике условие, лучше раздробить его. Например :
if ((a==b) and (b==c)) and ((a!=c)||(b!=c)) then //делаем что-то endif
Лучше оформить вот так (имена переменных должны быть понятными, что за результат они хранят):
var isValueValid = (a==b) and (b==c); var isNoErrors = (a!=c)||(b!=c); if isValueValid and isNoErrors then //делаем что-то endif
3. Если последовательность кода заключена в операторные скобки (procedure/endprocedure; if/endif; function/endfunxtion), то эту последовательность необходимо смещать tab’ами или пробелами на единое расстояние, а операторные скобки что бы располагались ровно одна под другой. Т.е. чтобы код выглядел «лесенкой».
Неправильно :
procedure Test(InParam) if InParam==1 then var a=inParam+3; endif endprocedure
Правильно :
procedure Test(InParam)
if InParam==1 then
var a=inParam + 3;
endif
endprocedure
4. Старайтесь собственные процедуры разбивать на более мелкие. Идеально, когда одна отдельно взятая процедура/функция занимает не более 10-15 строк.
Неправильно :
function OnHeroAnswer(UnitName, AnswerID)
var hero;
var bot = CreateObject("MapObject");
var isExist = bot.GetObjectByName(UnitName);
if not isExist then
bot.Free();
return false;
endif
if UnitName == "roma" then
// логика для юнита "roma"
endif
if UnitName == "pasha" then
// логика для юнита "pasha"
endif
if UnitName == "pasha" then
// логика для юнита "ivan"
endif
…….
//На 300 строк кода
return false;
endfunction
Правильно :
function mGetRomaQuestion(AnswerId)
// логика для юнита "roma"
endfunction
function mGetPashaQuestion(AnswerId)
// логика для юнита "pasha"
endfunction
function mGetIvanQuestion(AnswerId)
// логика для юнита "Ivan"
endfunction
function OnHeroAnswer(UnitName, AnswerID)
var hero;
var bot = CreateObject("MapObject");
var isExist = bot.GetObjectByName(UnitName);
if not isExist then
bot.Free();
return false;
endif
if UnitName == "roma" then
return mGetRomaQuestion(AnswerId)
endif
if UnitName == "pasha" then
return mGetPashaQuestion(AnswerId)
endif
if UnitName == "ivan" then
return mGetIvanQuestion(AnswerId)
endif
return false;
endfunction
Такой способ разбиения большой процедуры на более мелкие:
- Поможет Вам разобраться в собственной писание.
- Локализует ошибки (Вы быстрее их найдете в более мелкой процедурке, нежели в большой, но 300 строк)
- Такой способ поможет третьему лицу, который будет изучать Ваш код.
Именование
1. Имена переменных, процедур, функций должны быть на английском ! Имя должно характеризовать содержимое переменной или действие процедуры/функции. . Имя должно быть не более 15-17 символов, для удобства чтения. Категорически неправильно :
function raschet_znazeniya(a) // Имя процедуры на транслите - поймут только русские, а проект международный var ttt=1; // для чего эта переменная предназначена ? return ttt+a //что хранит в себе параметр ? endfunction
Правильно :
function mCalculateValue(UnitHealth)
var healthUp=1;
return UnitHealth + healthUp
endfunction
Исключение правил именования только составляют "привычные" индексы - i и j. А также размерность n или m.
2. Имена всех локальных переменных, локальных процедур, функций должны быть в формате Camel Case. Это означает, что имя, состоящие из нескольких слов, пишется по следующим правилам :
А) Все имя целиком пишется одним словом
Б) Первое слово ВСЕГДА пишется маленькими (прописными) буквами, все остальные – с большой (первая буква в слове – большая, все остальные в слове - маленькие).
Пример, имен написаных в формате Camel Case:
myFirstVariable, result, calculatedParameter
3. Имена всех предопределённых процедур (событий)и функций, а также глобальных процедур/функций для UserModule, должны быть в формате Pascal Case.
Это означает, что имя, состоящие из нескольких слов, пишется по следующим правилам :
А) Все имя целиком пишется одним словом
Б) Первое слово ВСЕГДА пишется с Большой буквы (первая буква в слове – большая, все остальные в слове - маленькие) и все остальные слова пишутся с большой (заглавной) буквы.
Пример, имен написаных в формате Pascal Case:
MyFirstVariable, Result, CalculatedParameter
4. Имена всех константных значений (т.е. тех, которые в процессе выполнения программы не изменяются), должны быть оформлены в формате "венгерской" записи - слова разделяются символом подчёркивания "_" и только заглавными буквами.
Пример :
UNIT_NAME, PISTOL_ITEM_NAME, MY_CITY_NAME
5. Имена локальных (не предопределённых), т.е. ВАШИХ процедур/функций должны начинаться с префикса “m” от слова "member".
Пример :
function mCalculateValue(InParameter)
var prefix=1;
return InParameter + prefix
endfunction
6. Имена логических переменных (те которые хранят результат TRUE/FALSE или 1/0) лучше начинать с префикса is
Например :
var isParamValid = (a > b);
Для функций это правило также применимо : Например :
function mIsUnitCanTalk(UnitName)
Для чего это делается
Особые формы стиля очень полезны, т.к. читающий Ваш код человек, знакомый с вышеописанными правилами, будет осознавать назначение, область видимости (глобальная/локальная) той или иной переменной(процедуры). Например, зная, что имя локальной переменной идет в стиле camelCase (начинается с маленькой буквы), читающий уже понимает, что переменная перед ним unitName - локальная и не надо лесть вверх по коду, чтобы узнать как она объявляется. Далее - из имени переменной понятно, что она хранит имя юнита.
Советы по оптимизации кода
1. Если в вашей процедуре/функции есть обработка нескольких условий, и при решении каждого из них можно выходить из тела процедуры/функции, то нужно это сделать при помощи оператора return (для функций надо return <значение>). Это необходимо для того, что бы интерпретатор не обрабатывал следующие за верным решением другие операторы в Вашей процедуре/функции. Например, вот этот код :
function mGetHealth(Weight)
var result = 0;
if Weight==10 then
result = 15;
endif
if Weight==20 then
result = 35;
endif
if Weight>30 then
result = 50;
endif
return result;
endfunction
Лучше сделать вот так :
function mGetHealth(Weight)
if Weight==10 then
return 15
endif
if Weight==20 then
return 35
endif
if Weight>30 then
return 50
endif
return 0
endfunction