Предлагаю цикл статей по оформлению кода на C/C++ для встраиваемых систем. Написать о стиле целиком ЂЂЂ довольно большая работа, поэтому я решил разбить ее на цикл статей. После того, как весь стандарт будет написан, я скомпилирую pdf с квинтэссенцией (О_о), который можно будет распечатать и пользоваться как руководство в вашей работе. Объединим эмбеддеров Руси! 1. Цель стандарта Создание вменяемого стандарта (стиля) написания и оформления кода ЂЂЂ это, пожалуй, первый и самый простой способ повысить его качество. Очень важно, чтобы программист при просмотре чужого кода быстро понимал его. Читаемость кода достигается шаблонизацией типичных выражений и соглашением о наименовании. Такой подход позволяет задействовать быстрые ассоциативные механизмы нашего мозга и не привлекать медленное сознание там, где без него можно обойтись. Также, единый стиль позволяет учесть часто встречающиеся ошибки в кодировании и избежать их. Я решил не изобретать велосипед. За основу взят стандарт оформления кода google: Я лишь уточняю моменты, не описанные в этом стандарте. И адаптирую стандарт для применения во встраиваемых системах. 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 Примеры:
Опубликовано в рубрике " ", 8 марта, 2010.
Страничка эмбеддера » Стиль С/С++. Соглашения о именах.
Комментариев нет:
Отправить комментарий