Предлагаю цикл статей по оформлению кода на C/C++ для встраиваемых систем. Написать о стиле целиком – довольно большая работа, поэтому я решил разбить ее на цикл статей. После того, как весь стандарт будет написан, я скомпилирую pdf с квинтэссенцией (О_о), который можно будет распечатать и пользоваться как руководство в вашей работе.

Объединим эмбеддеров Руси!

 

1. Цель стандарта

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

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

Также, единый стиль позволяет учесть часто встречающиеся ошибки в кодировании и избежать их.

Я решил не изобретать велосипед. За основу взят стандарт оформления кода google:

https://google-styleguide.googlecode.com/svn/trunk/cppguide.xml

Я лишь уточняю моменты, не описанные в этом стандарте. И адаптирую стандарт для применения во встраиваемых системах.

 

2. Зачем?

Зачем новый стандарт? Чем от отличается от других, к примеру, от стандарта Micrium?

Во-первых, этот стандарт не является новым и является fork’ом или клоном (кому как удобнее) стандарта гугла. Я лишь уточнаяю некоторые моменты.

Во-вторых, этот стандарт больше ориентирован на скорость написания кода при сохранении качества, чем на бескомпромиссное качество при очень низкой скорости написания кода.

Во-третьих, этот стандарт является родным, русскоязычным и именно вы, да,-да, вы принимаете участие в его создании.

В-четвертых, этот стандарт (в отличии от многих других стандартов кодирования для встраиваемых систем) допускает применение С++.

В любом случае (даже, если этот стандарт не станет распространенным), как минимум я для себя формализую свой стиль написания кода, что поможет мне в будущем.

Итак, поехали!

Это первая, тестовая часть и сегодня мы опишем самое важное – имена.

 

3. Имена

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

 

3.1 Общие правила

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

Никогда! Никогда! Не называйте переменные и функции транслитом!

Пример хорошо выбранных имен переменных:

int num_errors;                           // Хорошо.
int num_completed_connections;   // Хорошо.

Пример плохо выбранных имен переменных:

int n;                                         // Плохо — бессмысленно.
int nerr;                                     // Плохо – двусмысленная аббревиатура.
int n_comp_conns;                     // Плохо – двусмысленная аббревиатура.

Имена переменных и типов должны быть существительными MidiHeader, num_of_errors

Имена функций должны быть “командами”: OpenFile(), SetUartBaudRate(). Активно используйте слова Set и Get

 

Стоит избегать аббревеатур, за исключением общеизвестных.

// Хорошо
int num_dns_connections;  // Большинство людей знает, что такое DNS

// Плохо
int wgc_connections;  // Только ваша команда знает, о чем речь.
int pc_reader;            // Много разных вещей можно обозначить как “pc”

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

// Хорошо

class SpiDriver;

// Плохо

uint8 SPIGetChar();

3.1 Названия типов

В названиях всех типов – классов, структур, enum’ов и typedef’ов следует каждое новое слово начинать с большой буквы, не разделяя слова.

class UrlTable { …
class UrlTableTester { …
struct UrlTableProperties { …

// typedefs
typedef hash_map<UrlTableProperties *, string> PropertiesMap;

// enums
enum UrlTableErrors { …

 

3.2 Названия переменных

Имена переменных состоят из слов с подчерками между ними. К названиям переменных – членов класса добавляется подчерк.

К примеру:

Обычные переменные:

// Хорошо
string table_name;

// Плохо
string tableName;

Переменные-члены класса:

string table_name_;  // Подчерк

Переменные в структурах обозначаются как обычные переменные:

struct UrlTableProperties
{
  string name;
  int num_entries;
};

Глобальные переменные. К названию глобальной переменной следует добавить префикс g_

 

3.3 Названия функций

Название функций точно такое-же, как и название типов. Каждое новое слово – с большей буквы

AddTableEntry()
DeleteUrl()

Если – член класса используется только для получения доступа к переменной, она обозначается так-же как и переменная.

class MyClass {
public:
  …

  void DoCountEntries();
  int num_entries() const { return num_entries_; }
  void set_num_entries(int num_entries) { num_entries_ = num_entries; }

private:
  int num_entries_;
};

3.4 Названия констант

Названия констант сильно отличается от названия обычных переменных. Их следует именовать смешанным регистром (как функции или типы) и префиксом k.

К примеру:

const int kDaysInAWeek = 7;

3.5 Названия перечислений

Перечисления именуются так-же, как и константы.

enum UrlTableErrors
{
  kOK = 0,
  kErrorOutOfMemory,
  kErrorMalformedInput,
};

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

enum AlternateUrlTableErrors
{
  OK = 0,
  OUT_OF_MEMORY = 1,
  MALFORMED_INPUT = 2,
}

 

3.6 Названия макросов

Макросы называются следующим образом:

#define ROUND(x) …
#define PI_ROUNDED 3.0

Стоит избегать использования макросов где это возможно и заменять их константами или inline функциями!

 

3.7 Имена файлов

Имена фалов должны быть уникальны и отдельные слова в именах должны разделяться подчерком. Не используйте имен, которые уже используются стандартной библиотекой.

Файлы, содержащие С++ код должны иметь расширение .cpp, файлы содержащие с код — .с заголовочные файлы — .h

Если вам необходимо создать большую inline функцию, или много коротких inline функций, создайте для них файл с окончанием –inl.h

Примеры:

url_table.h      // Обьявление класса или интерфейс модуля.
url_table.cpp   // Реализация класса или модуля.
url_table-inl.h  // Множество inline – функций

 

3.8 Исключения

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

К примеру:

myfopen()                         // функция, подобная стандартной fopen()
uint                                  // typedef от int
sparse_hash_map             // STL-подобная сущность
UINT8_MAX                      // константа, как INT_MAX

 

На сегодня – все. Ваша критика, ваши дополнения и ваша благодарность приветствуются!