Code Style Guide

Table of Contents Именование переменных в коде Оформление классов (синтаксис) Приватные переменные Пример Оформление классов (семантика) Оформление enum'ов(перечислений) Проверка типов данных Написание DEBUG конструкций

Именование переменных в коде

Для всех переменных, которые не входят в список зарезервированных слов, обязательны префиксы.

Тип / Назначение	Префикс	Примеры	Дополнительно
[E]Enum	E	EParams, EBlendModes	E - для перечислений
[I]Interface	I	IEngine, IDisplayManager, ICamera	I - для интерфейсов
[U]Int[8,16,32,64]	i,n	iCount, iStride, iSize, nTotal, nBytes	i - для Int, n - для Uint-счетчиков
Constants	c	cFormat, csExtansion	Это может быть как константа строки(тогда префикс должен быть cs - const string), так и числа(c или ci, cf - для float).
String	s	sName, sValue, sHash
Float[32,64]	f	fValue, fSumm, fResult
Boolean	b,is,has,have,use,can	isEmpty, hasSemantics, bValuem, canRun	Используйте префикс b только в случаях, когда остальные заведомо не подходят.
Vectors	v[0-9][f,i]	v4fLength, v3fPosition, v2iCoord, v2iCenter	v - означает, что это вектор, далее число компонент вектора, далее тип компонент, f - Float, i - Int.
Quaternion	q	qRotation	q - означает, что это кватернион.
Matrix	m[0-9][f,i]	m4fProjection, m3fRotation, m2iScale	m - означает, что это матрица, далее размер, 3 - для 3x3 матриц, далее тип компонент, f - Float, i - Int.
Color	c([3,4][f,i])	c4fRed, c3iBlue, cValue	c - означает, что это цвет, далее, опционально, число компонент, далее тип компонент, f - Float, i - Int.
Type	t	tHash, tData	используется для обозначения переменных, содержащих тип данных.
Object	p	pData, pVertexDeclaration, pObject	используется для обозначения переменных, содержащих ссылку на объект. Массивы также входят в эту категорию.
Function	fn	fnCallback, fn, fnSuccess	используется для обозначения переменных, содержащих функции.
Enumeration	e	eOptions, eFlag	используется для обозначения переменных, содержащих ключи или комбинации ключей из Enum'ов.

Список зарезервированных слов, которые можно использовать без префикса.

1. Все переменные в одну букву.
2. tmp - для переменной, временного хранилища
3. src - source, для обозначения входных данных.
4. dst - destination, для обозначения выходных данных
5. id - для численных идентификаторов.

Оформление классов (синтаксис)

• Все объекты движка(за исключением примитивных, вроде векторов) должны иметь интерфейсы.
• Интерфейсы описывают только публичные методы.
  • Например для создания класса камеры, вы должны создать сначала интерфейс ICamera.
• Классы не могут содержать публичных переменных(за исключеним статических)
• Все переменные класса должны быть объявлена в самом начале.
• Все геттеры и сеттеры класса должны быть объявлены сразу за переменными.
  • Все гетеры и сеттеры должны стоять парами(если они предназначены для одного и того же свойства)
  • Публичные(public) и методы должны быть объявлены до защищенных(protected), а те в свою очередь до приватных. (private)
  • Первым публичным методом всегда должен быть конструктор(если он вообще есть).
  • У публичных методов никогда не должно быть ключего слова public.
• Статические переменные и методы должны распологаться в самом низу класса.
  • Причем методы идут после переменных.

Приватные переменные

• Имена всех приватных переменных должны начинаться с _ (подчеркивания). Например: _sName, _pData ...

Пример

Vec2 {
        x: number;
        y: number;
 
        private _bNomilized: bool = false;

        constructor ();
        constructor (v2f: Vec2);
        constructor (x: number, y: number);
        constructor (x?, y?) {
           //...
        }


        set(): Vec2;
        set (v2f: Vec2): Vec2;
        set (x: number, y: number): Vec2;
        set (x?, y?): Vec2 {
            //...
        }
        
        private calcMagic(): void {}

        static pOrigin: Vec2 = new Vec2;
    }

Оформление классов (семантика)

• Порядок объявления методов в интерфейсе класса и самом классе должны совпадать.
• Доступ ко всем приватным переменным должен осуществляться через одноименные геттеры и сеттеры.
  • Все геттеры и сеттеры должны быть помечены как @inline
• Для получения всевозможных простых(тех, которые в дальнейшем могут быть проинлайнены) свойств класса должны быть использованы геттеры.
• Все методы класса, которые выполняют схожую работу должны быть объявлены в одной группе.
  • Группы методов отделяются друг от друга двумя(или более) пустыми строками.
• Методы класса должны быть объявлены в том порядке, в котором они используются в коде.
• Все одноименные методы(т.е. перегрузки) должны быть объявлены рядом, и отсортированы по числу аргументов.

Оформление enum'ов(перечислений)

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

 export enum EResourceItemEvents{
	k_Created, 			//ресур создан
	k_Loaded, 			//ресур заполнен данным и готов к использованию
	k_Disabled, 		//ресур в данный момент отключен для использования
	k_Altered, 			//ресур был изменен после загрузки
	k_TotalResourceFlags
};

Проверка типов данных

Для проверки типов данных, а akra engine существует ряд встроенных функций, они нужны для повышения читабельности кода и улучшения переносимости. Опепатор typeof НЕ РЕКОМЕНДОВАН к использованию. Если есть необходимость, используйте функцию typeOf(x:any):string

Название	Назначение
isDef(x: any): bool	Проверка, не является ли x - undefined
isNull(x: any): bool	Проверка, является ли x - null
isBoolean(x: any): bool	Проверка, является ли x - bool
isString(x: any): bool	Проверка, является ли x - string
isNumber(x: any): bool	Проверка, является ли x - number
isFloat(x: any): bool	Проверка, является ли x - float
isInt(x: any): bool	Проверка, является ли x - int
isFunction(x: any): bool	Проверка, является ли x - function
isObject(x: any): bool	Проверка, является ли x - object
isArray(x: any): bool	Проверка, является ли x - array

Написание DEBUG конструкций

В коде определена константа DEBUG, определенная в TRUE для DEBUG сборки. //TODO