как правильно оформлять код c
Гайд по оформлению кода на С++ от Стэнфордского университета
Стэнфордский университет представил гайд по основным стандартам оформления кода на С++. Умение корректно оформить ваш код является ценным навыком, так как это в разы облегчает работу других. Также у нас есть подобная статья, посвящённая написанию самодокументируемого кода.
Пробелы и отступы
Отделяйте пробелами фигурные скобки:
Ставьте пробелы между операторами и операндами:
Когда строка становится длиннее 100 символов, разделите её на две, сделав перевод на новую строку после оператора, и продолжайте писать:
Оставляйте пустые линии между функциями и между группами выражений:
Названия и переменные
Используйте текстовую строку, стандартную для C++, а не С. С++ путает тем, что имеет два вида текстовых строк: класс string из С++ и старый char* (массив символов) из С:
Если определенная константа часто используется в вашем коде, то обозначьте её как const и всегда ссылайтесь на данную константу, а не на её значение:
Никогда не объявляйте изменяемую глобальную переменную. Глобальными переменными должны быть только константы. Вместо того, чтобы делать значение глобальным, сделайте его параметром и возвращайте значение, когда необходимо:
Базовые выражения С++
Чрезмерность
Если вы используете один и тот же код дважды или более, то найдите способ удалить излишний код, чтобы он не повторялся. К примеру, его можно поместить во вспомогательную функцию. Если повторяемый код похож, но не совсем, то постарайтесь сделать вспомогательную функцию, которая принимает параметры и представляет разнящуюся часть:
Комментарии
Заглавный комментарий. Размещайте заглавный комментарий, который описывает назначение файла, вверху каждого файла. Предположите, что читатель вашего комментария является продвинутым программистом, но не кем-то, кто уже видел ваш код ранее.
Заголовок функции / конструктора. Разместите заголовочный комментарий на каждом конструкторе и функции вашего файла. Заголовок должен описывать поведение и / или цель функции.
Параметры / возврат. Если ваша функцию принимает параметры, то кратко опишите их цель и смысл. Если ваша функция возвращает значение — кратко опишите, что она возвращает.
Исключения. Если ваша функция намеренно выдает какие-то исключения для определенных ошибочных случаев, то это требует упоминания.
Комментарии на одной строке. Если внутри функции имеется секция кода, которая длинна, сложна или непонятна, то кратко опишите её назначение.
TODO. Следует удалить все // TODO комментарии перед тем, как заканчивать и сдавать программу.
Эффективность
Вызывая большую функцию и используя результат несколько раз, сохраните результат в переменной вместо того, чтобы постоянно вызывать данную функцию:
Функции и процедурное проектирование
Хорошо спроектированная функция имеет следующие характеристики:
Когда требуется вернуть значение из функции, используйте значение return :
Отправляя объект в функцию как параметр, вы должны передавать его по ссылке, так как если он будет передан как значение, то будет скопирован весь объект. Копирование объектов требует больших затрат памяти.
Используйте ссылочные переменные, а не указатели. Одна из причин — это то, что ссылочные переменные, в отличие от указателей, не могут принимать значение NULL :
Проектирование классов
Инкапсуляция. Отделяйте ваши объекты, делая все поля данных в вашем классе private :
Избегайте ненужных полей. Используйте поля, чтобы хранить важные данные о ваших объектах, но не временные значения, которые используются единожды.
C#: требования и рекомендации по написанию кода
Я немного поизучал имеющиеся предложения из этих источников:
submain.com/blog/FreeCVBNETCodingGuidelinesEbookDownload.aspx
idesign.net/idesign/DesktopDefault.aspx
и скомпилировал черновик который описывает самые базовые правила оформления кода написанного на C#.
Предлагаю:
— обсудить этот черновик;
— внести в него все необходимые изменения;
— утвердить как стандарт написания C# кода на Хабре.
Более того, предлагаю создать документ, который можно было бы предложить как рекомендации habrahabr comunity для всех других программистов C#.
Под катом вы найдете текст черновика. Предлагаю всем желающим обсудить его и подвергнуть надлежащей правке.
1. Требования
1.1 Pascal casing
namespace SampleNamespace
<
enum SampleEnum
<
FirstValue,
SecondValue
>
struct SampleStruct
<
public int FirstField;
public int SecondField;
>
interface ISampleInterface
<
void SampleMethod();
>
public class SampleClass: SampleInterface
<
const int SampleConstValue = 0xffffff;
readonly int SampleReadonlyField;
public int SampleProperty
<
get ;
set ;
>
public int SamplePublicField;
SampleClass()
<
SampleReadonlyField = 1;
>
delegate void SampleDelegate();
event SampleDelegate SampleEvent;
1.2 Camel casing
protected int sampleProtectedField;
1.3 Суффиксы и префиксы
public class SampleException: System. Exception
<
public SampleException()
<
>
>
interface ISample
<
void SampleMethod();
>
1.4 Аббревиатуры
2. Рекомендации
2.1 Именование методов
В частном случае, для методов, которые возвращают значение, используйте в паре глагол-объект для глагола «Get», а для объекта – описание возвращаемого значения.
2.2 Переменные, поля и свойства
• При именовании переменных избегайте использования сокращенных вариантов вроде I и t, используйте index и temp. Не используйте венгерскую нотацию или используйте ее только для закрытых членов. Не сокращайте слова, используйте number, а не num.
• Рекомендуется для имен элементов управления указывать префиксы, описывающие тип элемента. Например: txtSample, lblSample, cmdSample или btnSample. Эта же рекомендация распространяется на локальные переменные сложных типов: ThisIsLongTypeName tltnSample = new ThisIsLongTypeName();
• не используйте публичных или защищенных полей, вместо этого используйте свойства;
• используйте автоматические свойства;
• всегда указывайте модификатор доступа private, даже если разрешено его опускать;
• всегда инициализируйте переменные, даже когда существует автоматическая инициализация.
2.3 Дополнительные рекомендации
2.4 Объем кода
• избегайте файлов с более чем 500 строками кода;
• избегайте методов с более чем 200 строками кода;
• избегайте методов с более чем 5 аргументами, используйте структуры для передачи большого числа параметров;
• одна строка кода не должна иметь длину более 120 символов.
3. Спорные моменты для обсуждения
3.1 Закрытые поля
private int m_SamplePrivateField;
private int mSamplePrivateField;
private int _samplePrivateField;
Руководство Google по стилю в C++. Часть 1
Часть 1. Вступление
Часть 2. Заголовочные файлы
Часть 3. Область видимости
Часть 4. Классы
…
Часть 8. Именование
Часть 9. Комментарии
Часть 10. Форматирование
… 
Все мы при написании кода пользуемся правилами оформления кода. Иногда изобретаются свои правила, в других случаях используются готовые стайлгайды. Хотя все C++ программисты читают на английском легче, чем на родном, приятнее иметь руководство на последнем.
Эта статья является переводом части руководства Google по стилю в C++ на русский язык.
Исходная статья (fork на github), обновляемый перевод.
Это вступительная часть руководства, в которой рассматриваются общие вопросы «Зачем?»
Также после перевода будет несколько ответов на возможные вопросы.
Вступление
C++ один из основных языков программирования, используемый в open-source проектах Google.Известно, что C++ очень мощный язык. Вместе с тем это сложный язык и, при неправильном использовании, может быть рассадником багов, затруднить чтение и поддержку кода.
Цель руководства — управлять сложностью кода, описывая в деталях как стоит (или не стоит) писать код на C++.Правила этого руководства упростят управление кодом и увеличат продуктивность кодеров.
Style / Стиль — соглашения, которым следует C++ код.Стиль — это больше, чем форматирование файла с кодом.
Большинство open-source проектов, разрабатываемых Google, соответствуют этому руководству.
Примечание: это руководство не является учебником по C++: предполагается, что вы знакомы с языком.
Цели Руководства по стилю
Зачем нужен этот документ?
Есть несколько основных целей этого документа, внутренних Зачем, лежащих в основе отдельных правил. Используя эти цели можно избежать длинных дискуссий: почему правила такие и зачем им следовать. Если вы понимаете цели каждого правила, то вам легче с ними согласиться или отвергнуть, оценить альтернативы при изменении правил под себя.
Цели руководства следующие::
Использование единого стиля на кодовой базе позволяет переключиться на другие, более важные, вопросы.
В C++ есть возможности, которые в целом не приветствуются по причине усложнения кода.
Однако, в часто используемом коде применение хитрых конструкций более оправданно благодаря многократному использованию, также новые порции кода станут более понятны.
В случае сомнений — проконсультируйтесь с лидером проекта.
Оптимизация производительности иногда важнее, чем следование правилам в кодировании.
Намерение этого документа — обеспечить максимально понятное руководство при разумных ограничениях. Как всегда, здравый смысл никто не отменял. Этой спецификацией мы хотим установить соглашения для всего сообщества Google в C++, не только для отдельных команд или людей. Относитесь со скепсисом к хитрым или необычным конструкциям: отсутствие ограничения не всегда есть разрешение. И, если не можешь решить сам, спроси начальника.
Версия C++
Сейчас код должен соответствовать C++17, т.е. возможности C++2x нежелательны. В дальнейшем, руководство будет корректироваться на более новые версии C++.
Учитывайте совместимость с другим окружением, если собираетесь использовать C++14 and C++17 в свойм проекте.
Прим.: ссылки могут вести на ещё не переведённые разделы руководства.
Лично мне удобнее с русским руководством. Обсуждать изменения в стайлгайде также лучше с русским текстом
— Почему Google? Есть более (или менее) популярные…?
Компания вполне известная, руководство не очень большое (можно без напряга перевести силами одного человека), отвечает требуемым функциям — это руководство именно по стилю
— Но в руководстве Google декларируется использование устаревших (. ), отказ от таких полезных (. )! Зачем?
Насколько я понял, этот документ — предложение. Что-то вы будете использовать, что-то измените — это допустимо. Руководство — хорошая основа.
Учимся правильно оформлять код на C на примере open source проектов
Учимся правильно оформлять код на C на примере open source проектов
В каждом проекте есть свои соглашения по написанию и оформлению кода. Некоторые менеджеры ограничиваются только базовыми правилами, некоторые составляют подробные списки рекомендаций. В некоторых проектах правил оформления кода нет совсем, и каждый разработчик следует своему стилю.
Если исходники большого проекта написаны в одном стиле, их гораздо легче понимать.
Научиться правильному оформлению кода можно, например:
Другой, не менее интересный, подход — взять проверенный временем открытый проект и разобраться в том, какие решения принимали его разработчики. Хорошим примером в этом случае будет ядро Linux.
Для новичка или даже для опытного разработчика, разбор кода ядра Linux может оказаться непростой задачей. Однако наша цель не присоединиться к ним, а просто рассмотреть детали реализации.
Давайте посмотрим на пример реализации функции из исходного кода Linux:
Код выглядит чистым и понятным:
Тот же код, написанный другим разработчиком, может выглядеть так:
Стиль написания кода очень сильно влияет на его читаемость. Поэтому время, потраченное на тренировку и периодические код-ревью, всегда окупится.
Давайте теперь посмотрим на код ядра Linux с помощью CppDepend и попробуем разобраться, какими правилами руководствовались разработчики.
Модульность
Модульность — это техника дизайна приложений, которая обеспечивает повторное использование кода и облегчает его поддержку.
Для процедурного языка, такого, как C, в котором нет пространств имен, классов или компонентов, мы можем разделять модули, помещая код в отдельные файлы и директории.
Мы можем использовать два подхода:
В случае с ядром Linux директории и поддиректории используются для обеспечения модульности кода ядра.
Инкапсуляция
Давайте посмотрим на статические функции с помощью следующего запроса в CQLinq:
Мы можем использовать панель Метрик (Metric view) чтобы оценить код в целом. На этой панели код представлен в виде дерева (Treemap). Древовидная структура, используемая в CppDepend показывает иерархию кода:
Дерево проекта позволяет наглядно представить результаты запроса CQLinq.
Видно, что множество функций — статические.
Теперь давайте найдем статические поля:
В коде ядра Linux инкапсуляция используется каждый раз, когда доступ к функции или переменной должен быть разрешен только из того же файла.
Используйте структуры для своих данных
В C функции используют переменные для работы. Переменные могут быть:
В каждом проекте есть модель данных, которая используется в различных модулях. Использование глобальных переменных для представления этой модели — это возможное решение, но плохое. Используйте структуры для группировки данных.
Давайте найдем все глобальные переменные с примитивным типом:
Их всего несколько, и, возможно, мы могли бы сгруппировать их в структуры, например ( elfcorehdr_addr и elfcorehdr_size ) или ( pm_freezing и pm_nosig_freezing ).
Функции должны быть краткими и понятными
Вот совет из linux coding style по поводу длины функции:
Функции должны быть короткими и понятными, делать только одну вещь. Они должны занимать один или, максимум, два экрана текста (экран по ISO/ANSI имеет размер 80×24). Функция должна делать одну вещь, и делать ее хорошо.
Максимальная длина функции обратно пропорциональна ее сложности и количеству уровней вложенности. Так, если у вас, например, простая функция с одним, но большим case-выражением, она может быть длинной.
Давайте найдем все функции, длина которых больше 30 строк:
Всего немного методов занимает больше 30 строк.
Количество параметров функции
Функции с количеством параметров большим, чем 8 (NbParameters > 8), трудно вызывать. Также, их вызов плохо сказывается на производительности. Вместо этого мы можем передавать в них структуру с необходимыми значениями.
Только два метода принимают больше, чем 8 параметров.
Количество локальных переменных
Методы, в которых используются более 8 локальных переменных (значение NbVariables) тяжело понимать и поддерживать. Методы, в которых 15 и более локальных переменных очень сложны и их следует разбивать на более мелкие (кроме тех случаев, когда код сгенерирован сторонним инструментом).
Только в пяти функциях используется более 15 локальных переменных.
Избегайте сложных функций
Существует много метрик для определения сложности функции. Количество строк кода, локальных переменных и параметров — только некоторые из них.
Есть несколько более комплексных метрик:
Максимально допустимые значения этих метрик устанавливаются руководителем, здесь нет стандартных значений.
Давайте посмотрим на функции, которые можно упростить:
Только небольшое количество функций можно признать сложными.
Соглашения об именовании
Не существует единого стандарта именования элементов программы, поэтому каждый менеджер проекта может устанавливать свои правила, однако важно, чтобы эти правила были последовательны.
К примеру, в коде ядра Linux имена структур должны начинаться со строчной буквы. Мы можем проверить соответствие кода соглашению с помощью такого запроса:
Имена только 4 структур начинаются с «_» вместо строчной буквы.
Отступы и выравнивание
Отступы очень важны для того, чтобы код был читаем. Вот что пишут об этом на странице linux coding style:
Обоснование: Основная идея отступов состоит в том, чтобы показать где начинается и заканчивается логический блок кода. Когда вы смотрите на один и тот же код в течение 20 часов, трудно не заметить пользу отступов.
Некоторые могут возразить, что отступ в 8 пробелов делает код слишком широким, особенно на 80-знаковой строке терминала. Ответ: Если вам понадобилось более трех уровней отступа, вы что-то делаете неправильно и вам следует переписать этот участок.
Заключение
Чтение кода open-source проектов всегда идет на пользу вашему опыту. При этом нет необходимости скачивать и собирать проект, достаточно просто просматривать код, например, на GitHub.
Руководство Google по стилю в C++. Часть 8
Все мы при написании кода пользуемся правилами оформления кода. Иногда изобретаются свои правила, в других случаях используются готовые стайлгайды. Хотя все C++ программисты читают на английском легче, чем на родном, приятнее иметь руководство на последнем.
Эта статья является переводом части руководства Google по стилю в C++ на русский язык.
Исходная статья (fork на github), обновляемый перевод.
Именование
Основные правила стиля кодирования приходятся на именование. Вид имени сразу же (без поиска объявления) говорит нам что это: тип, переменная, функция, константа, макрос и т.д. Правила именования могут быть произвольными, однако важна их согласованность, и правилам нужно следовать.
Общие принципы именования
Отметим, что типовые имена также допустимы: i для итератора или счётчика, T для параметра шаблона.
В дальнейшем при описании правил «word» / «слово» это всё, что пишется на английском без пробелов, в том числе и аббревиатуры. В слове первая буква может быть заглавной (зависит от стиля: «camel case» или «Pascal case»), остальные буквы — строчные. Например, предпочтительно StartRpc(), нежелательно StartRPC().
Параметры шаблона также следуют правилам своих категорий: Имена типов, Имена переменных и т.д…
Имена файлов
Имена файлов должны быть записаны только строчными буквами, для разделения можно использовать подчёркивание (_) или дефис (—). Используйте тот разделитель, который используется в проекте. Если единого подхода нет — используйте «_».
Примеры подходящих имён:
Не используйте имена, уже существующие в /usr/include, такие как db.h.
Старайтесь давать файлам специфичные имена. Например, http_server_logs.h лучше чем logs.h. Когда файлы используются парами, лучше давать им одинаковые имена. Например, foo_bar.h и foo_bar.cc (и содержат класс FooBar).
Имена типов
Имена типов начинаются с прописной буквы, каждое новое слово также начинается с прописной буквы. Подчёркивания не используются: MyExcitingClass, MyExcitingEnum.
Имена всех типов — классов, структур, псевдонимов, перечислений, параметров шаблонов — именуются в одинаковом стиле. Имена типов начинаются с прописной буквы, каждое новое слово также начинается с прописной буквы. Подчёркивания не используются. Например:
Имена переменных
Имена переменных (включая параметры функций) и членов данных пишутся строчными буквами с подчёркиванием между словами. Члены данных классов (не структур) дополняются подчёркиванием в конце имени. Например: a_local_variable, a_struct_data_member, a_class_data_member_.
Имена обычных переменных
Члены данных класса
Члены данных классов, статические и нестатические, именуются как обычные переменные с добавлением подчёркивания в конце.
Члены данных структуры
Члены данных структуры, статические и нестатические, именуются как обычные переменные. К ним не добавляется символ подчёркивания в конце.
См. также Структуры vs Классы, где описано когда использовать структуры, когда классы.
Имена констант
Объекты объявляются как constexpr или const, чтобы значение не менялось в процессе выполнения. Имена констант начинаются с символа «k», далее идёт имя в смешанном стиле (прописные и строчные буквы). Подчёркивание может быть использовано в редких случаях когда прописные буквы не могут использоваться для разделения. Например:
Все аналогичные константные объекты со статическим типом хранилища (т.е. статические или глобальные, подробнее тут: Storage Duration) именуются также. Это соглашение является необязательным для переменных в других типах хранилища (например, автоматические константные объекты).
Имена функций
Обычные функции именуются в смешанном стиле (прописные и строчные буквы); функции доступа к переменным (accessor и mutator) должны иметь стиль, похожий на целевую переменную.
Обычно имя функции начинается с прописной буквы и каждое слово в имени пишется с прописной буквы.
(Аналогичные правила применяются для констант в области класса или пространства имён (namespace) которые представляют собой часть API и должны выглядеть как функции (и то, что они не функции — некритично))
Accessor-ы и mutator-ы (функции get и set) могут именоваться наподобие соответствующих переменных. Они часто соответствуют реальным переменным-членам, однако это не обязательно. Например, int count() и void set_count(int count).
Именование пространства имён (namespace)
Пространство имён называется строчными буквами. Пространство имён верхнего уровня основывается на имени проекта. Избегайте коллизий ваших имён и других, хорошо известных, пространств имён.
Пространство имён верхнего уровня — это обычно название проекта или команды (которая делала код). Код должен располагаться в директории (или поддиректории) с именем, соответствующим пространству имён.
Не забывайте правило не использовать аббревиатуры — к пространствам имён это также применимо. Коду внутри вряд ли потребуется упоминание пространства имён, поэтому аббревиатуры — это лишнее.
Избегайте использовать для вложенных пространств имён известные названия. Коллизии между именами могут привести к сюрпризам при сборке. В частности, не создавайте вложенных пространств имён с именем std. Рекомендуются уникальные идентификаторы проекта (websearch::index, websearch::index_util) вместо небезопасных к коллизиям websearch::util.
Для internal / внутренних пространств имён коллизии могут возникать при добавлении другого кода (внутренние хелперы имеют свойство повторяться у разных команд). В этом случае хорошо помогает использование имени файла для именования пространства имён. (websearch::index::frobber_internal для использования в frobber.h)
Имена перечислений
Перечисления (как с ограничениями на область видимости (scoped), так и без (unscoped)) должны именоваться либо как константы, либо как макросы. Т.е.: либо kEnumName, либо ENUM_NAME.
Предпочтительно именовать отдельные значения в перечислителе как константы. Однако, допустимо именовать как макросы. Имя самого перечисления UrlTableErrors (и AlternateUrlTableErrors), это тип. Следовательно, используется смешанный стиль.
Вплоть до января 2009 года стиль именования значений перечисления был как у макросов. Это создавало проблемы дублирования имён макросов и значений перечислений. Применение стиля констант решает проблему и в новом коде предпочтительно использовать стиль констант. Однако, старый код нет необходимости переписывать (пока нет проблем дублирования).
Имена макросов
Вы ведь не собираетесь определять макросы? На всякий случай (если собираетесь), они должны выглядеть так:
MY_MACRO_THAT_SCARES_SMALL_CHILDREN_AND_ADULTS_ALIKE.
Пожалуйста прочтите как определять макросы; Обычно, макросы не должны использоваться. Однако, если они вам абсолютно необходимы, именуйте их прописными буквами с символами подчёркивания.
Исключения из правил именования
Если вам нужно именовать что-то, имеющее аналоги в существующем C или C++ коде, то следуйте используемому в коде стилю.
bigopen()
имя функции, образованное от open()
uint
определение, похожее на стандартные типы
bigpos
struct или class, образованный от pos
sparse_hash_map
STL-подобная сущность; следуйте стилю STL
LONGLONG_MAX
константа, такая же как INT_MAX
Прим.: ссылки могут вести на ещё не переведённые разделы руководства.