Стандарт оформления кода

Стандарт оформления кода очень значимая вещь особенно в командной разработке. Единый стиль помогает одинаково понятно читать как свой код так и чужой, скорость понимания кода значительно выше, нежели не стандартизированного.

Определение

Стандарт оформления кода (code style) — это набор определенных правил при написании исходного кода, на определенном языке программирования.

Пример: наш стандарт оформления кода.

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

Вся суть создания и использования стандарта оформления кода заключается:

  • легкости восприятия кода (повышение информативности)
  • легкости понимания смысла кода

То есть, суть выполняемых действий кодом, должна быть ясна из самого кода, без необходимости вникать в детали.

В общем случае стандарт оформления кода описывает:

  • методы именования данных, файлов
  • стили
    • отступов (вертикальные, горизонтальные)
    • логических блоков
    • комментариев

Методы именования файлов

в каждом проекте уникальны, и четких правил по этому поводу вряд ли найти. Мы в скриптовом языке s4g решили что все файлы с исходным кодом будут иметь префикс s4g_. Для движка уже такое будет не уместно, так как там очень много файлов, поэтому префиксы мы делать не стали.

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

достаточно сложная вещь, и требует наличие некоторого опыта для того чтобы точно определиться как нужно именовать. Мне для этого потребовалось около 6 лет))

Сюда входят:

  • правила использования префиксов, по типу той же венгерской нотации, для определения принадлежности переменной к какому -либо типу, либо иной ее идентификации
  • правила использования знаков подчеркивания (нижних пробелов), для разделения слов в переменных (к примеру: count_num)
  • правила использования верхнего и нижнего регистров, CamelCase (слова пишутся слитно, причем каждое слово с иного регистра), Upper — каждое слово начинается с верхнего регистра, lower — первое слово в нижнем регистре, а у остальных первая буква заглавная.
  • правила именования:
    • функций (глобальных и методов), а также их возможностей, к примеру есть стандарты которые допускают только одну группу действий в одном метода (если описать грубо: то есть либо только создать, либо только установить имя, а создать и установить имя не предусматривается),
    • симметричности именования методов классов (get/set, create/destroy, add/remove и так далее),
    • иттераторов
    • пространств имен,
    • переменных (в классе, глобальных, локальных),
    • классов,
    • дефайнов,
    • констант
    • и всего того что поддерживает язык

Формирование отступов

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

Вертикальные отступы помогает делить код целиком на блоки, пример:

const char* s4g_GC::getVarName(s4g_Variable *pVar, char* szName)
{
	if (!pVar || !(pVar->m_pOwner))
		return 0;

	static char szNameStatic[S4G_MAX_LEN_VAR_NAME];
	szNameStatic[0] = 0;

	if (pVar->m_pOwner->getType() == S4G_OWNERVAR_CONTEXT)
	{
		s4g_Context *pContext = (s4g_Context*)(pVar->m_pOwner);	
		ID idKey = pContext->m_pTable->getKeyByVar(pVar);
			
		if (idKey < 0) 
			return 0; 

		const char *szStr = pContext->m_pTable->getNameByNum(idKey);

		if (szName)
			sprintf(szName, szStr);

		return szStr;
	}

	s4g_Data *pOwner = (s4g_Data*)(pVar->m_pOwner);

	if (!pOwner)
		return 0;

	return getVarName2(pVar, szName);
}

Без вертикальных отступов:

const char* s4g_GC::getVarName(s4g_Variable *pVar, char* szName)
{
if (!pVar || !(pVar->m_pOwner))
return 0;

static char szNameStatic[S4G_MAX_LEN_VAR_NAME];
szNameStatic[0] = 0;

if (pVar->m_pOwner->getType() == S4G_OWNERVAR_CONTEXT)
{
s4g_Context *pContext = (s4g_Context*)(pVar->m_pOwner);
ID idKey = pContext->m_pTable->getKeyByVar(pVar);

if (idKey < 0) 
return 0; 

const char *szStr = pContext->m_pTable->getNameByNum(idKey);

if (szName)
sprintf(szName, szStr);

return szStr;
}

s4g_Data *pOwner = (s4g_Data*)(pVar->m_pOwner);

if (!pOwner)
return 0;

return getVarName2(pVar, szName);
}

Несомненно, первый вариант лучше.

Горизонтальные отступы помогают разделить код на части в одной строке, пример:

print(tostring(2 * (45 + ("qwe" + func(12 + 5))));

Пример без горизонтальных пробелов:

print(tostring(2*(45+("qwe"+func(12+5))));

Оформление логических блоков

помогает визуально отделить блок от всего другого кода и сфокусироваться только на блоке. Под блоками в данном случае понимаются управляющие конструкции языка C++ (if, else, for, while и другие).

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

значительно улучшает их читабельность, а значит ускоряет процесс понимания кода. Здесь также могут быть соглашения о комментариях, которые формируют документацию (документирующие комментарии), к примеру при помощи генератора документации doxygen.

Также стандарт оформления кода может запрещать некоторые возможности языка. Примером может служить оператор goto в С++, которые стараются многие избежать. Мы в своем стандарте его не запрещаем но не рекомендуем использовать.


В итоге, зачем нужен стандарт оформления кода — затем чтобы смысл кода был понятен из кода))

Рекомендую так же почитать на сторонних ресурсах:

Интересная статья, именно с нее начал составлять стандарт

Там же интересный опрос

Поделиться:

Добавить комментарий

Ваш e-mail не будет опубликован. Обязательные поля помечены *

*