Методология и руководство по стилю кода компании Ronimo

Руководство по стилю кода Ronimo

C++

• Весь код и комментарии пишутся на британском английском. (Не на американском английском.) Правильно: colour, centre, initialiser. Неправильно: color, center, initializer.
• За каждой запятой следует пробел, например: doStuff(5, 7, 8)
• Операторы отделяются пробелами, например: 5 + 7 вместо 5+7
• Табы имеют длину в четыре пробела. Табы хранятся как табы, а не как пробелы.
• Функции и статичные переменные указываются в одинаковом порядке в файлах .h и .cpp.
• Используйте #pragma once вместо #include guard (мы перешли к этому недавно, поэтому в нашем коде вы увидите много старых #include guard).
• Старайтесь писать короткие функции, желательно не длиннее 50 строк.
• Избегайте создания слишком больших классов. Если вы ожидаете, что класс сильно разрастётся и его можно логично разделить, то разделите его. Стремитесь к тому, чтобы стандартный размер класса не превышал 750 строк. Однако не стоит разделять класс, если код станет менее читаемым. Вот примеры нечитаемых разделений: слишком тесно связанные классы, классы friend и сложные иерархии классов.
• Не пишите длинные строки, которые не поместятся на стандартном экране 1920*1080 (не забывайте, что на этом экране есть и окно Solution Explorer).
• При разбиении длинной строки на несколько строк убедитесь, что отступы соответствуют скобкам. Например, вот так:
  
  

  myReallyLongFunctionName(Vector2(bananaXPos + xOffset,
                                   bananaYPos * multiplier),
                           explodingKiwi);

• По возможности пользуйтесь предварительным объявлением: в файлах заголовков должно быть как можно меньше include. Например, используйте class Bert; и переместите #include "Bert.h" в файл .cpp.
• Include и предварительные объявления должны иметь следующий порядок:
  
  • Начните со всех предварительных объявлений из вашего собственного кода (в алфавитном порядке)
  • Затем все include из вашего собственного кода (в алфавитном порядке)
  • Пустая строка
  • Затем для каждой библиотеки:
    
    • Предварительные объявления из этой библиотеки (в алфавитном порядке)
    • Все include из этой библиотеки (в алфавитном порядке)
• include файла .h, принадлежащий к файлу .cpp, всегда находится вверху.
• Не определяйте переменные static в функции. Используйте переменные элементов класса (возможно, статичные).
• Всё должно быть корректно с точки зрения const.
• Названия переменных и функций должны быть описательными. Можно без проблем использовать длинные названия, нельзя использовать невнятные названия. Используйте аббревиатуры, только если они очень понятны и стандартны.
• Первая буква названий классов, типов struct и enum — заглавная. Переменные и функции начинаются с прописной. Каждое следующее слово в названии начинается с заглавной буквы. Не используйте в названиях переменных символы подчёркивания ( _ ). Вот пример:
  
  

  class MyClass
  {
      void someFunction();
      int someVariable;
  };

• Переменные элементов никак не помечаются, ни буквой m перед названием, ни _ после. Функции должны быть достаточно короткими, чтобы можно было отслеживать то, что объявлено в функции, а что — в классе. Не помечайте переменные элементов this->.
• Реализации функций никогда не должны находиться в файлах .h.
• Шаблонные функции, которые невозможно реализовать в файле .cpp, реализуются в дополнительном файле заголовка, который подключается из основного файла заголовка. Такой класс может иметь три файла: MyClass.h, MyClassImplementation.h и MyClass.cpp. Например:
  
  

  class MyClass
  {
      template <typename T>
      void doStuff(T thingy);
  };
  
  #include "MyClassImplementation.h"

• Начинайте названия типов шаблонов с буквы T. Если нужно больше информации, то после неё можно добавить слова, например TString.
• Нельзя объявлять несколько классов в одном файле заголовка. Исключение: файл является частью другого класса (например, объявлен внутри другого класса).
• Между функциями должны быть две пустые строки (в файле .cpp).
• Используйте пустые строки для структурирования и группировки кода ради читаемости.
• Сопровождайте код подробными комментариями.
• Над каждым классом приводите короткое описание работы класса. В особенности стоит описывать взаимосвязи (например «Этот класс помогает классу X, выполняя за него Y»).
• Фигурные скобки { и } всегда занимают отдельную строку, то есть их нельзя помещать в одну строку с if или for. Также их никогда нельзя пропускать их. Единственное исключение: несколько похожих однострочных конструкций if, идущих одна под другой. В этом случае допускается поставить их в одной строке. Как в этом примере:
  
  

  if      ( banana &&  kiwi && length > 5) return cow;
  else if ( banana && !kiwi && length > 9) return pig;
  else if (!banana && !kiwi && length < 7) return duck;
  else                                     return dragon;

• При написании функции do-while while должно стоять в одной строке с закрывающей скобкой:
  
  

  do
  {
      blabla;
  } while (bleble);

• Отступы в конструкциях switch следует расставлять следующим образом:
  
  

  switch (giraffeCount)
  {
      case 1: text = "one giraffe";  break;
      case 2: text = "two giraffes"; break;
      case 3:
          // Если строк кода несколько
          doStuffOnSeveralLines;
          text = "three giraffes";
          break;
      case 4:
      {
          // Для читаемости можно добавить фигурные скобки
          int x = getComplexThing();
          text = "quadruple giraffe";
          break;
      }
  }

• Параметры функций должны иметь одинаковые названия в файлах .h и .cpp.
• Если параметр функции и переменная элемента класса имеют одинаковое название, то нужно или придумать другое название, или добавить _ в конце параметра функции. Например вот так:
  
  

  void setHealth(float health_)
  {
      health = health_;
  }

• Количество инструкций препроцессора (всё, начинающееся с #) должно быть минимальным, разумеется, за исключением #include и #pragma once.
• Не пишите макросы.
• Переменные внутри функций объявляются там, где они необходимы, не все их нужно объявлять в начале функции.
• В теле конструкторов лучше использовать списки инициализации (initialiser list), а не задавать переменные. Каждая инициализация в списке инициализации должна занимать отдельную строку. Убедитесь, что переменные в списке инициализации находятся в том же порядке, что и в определении класса в файле .h.
• Не используйте исключения (если вы не применяете библиотеку, которая их требует).
• Не используйте динамическую идентификацию типа данных (RTTI) (то есть не используйте dynamic_cast). RTTI немного снижает скорость, но более важно то, что RTTI почти всегда является свидетельством плохого объектно-ориентированного дизайна.
• Применяйте reinterpret_cast и const_cast только при абсолютной необходимости.
• Не делайте коммиты кода, который не компилируется без ошибок или предупреждений (и не отключайте сообщения о предупреждениях/ошибках).
• Не делайте коммиты кода, ломающего существующий функционал.
• Никаких глобальных переменных. Пользуйтесь вместо них переменными элементов типа static.
• Вместо std::abs используйте нашу собственную функцию MathTools::abs. Причина: реализация std::abs на разных платформах отличается, что приводит к труднообнаруживаемым ошибкам.
• Всегда используйте пространства имён явным образом. Не вставляйте в код ничего типа using namespace std.
• Даже не думайте использовать конструкции с go-to. У нас есть распознаватель мыслей и в таких случаях он бьёт программиста током.
• Не используйте в качестве разделителей запятые. Пример: if (i += 7, i < 10)
• Не используйте объединения union.
• Не применяйте указатели на функции, кроме случаев, когда этого требуют другие библиотеки (например, sort из STL).
• Используйте тернарные операторы только в простейших случаях. Никогда не используйте вложенные тернарные операторы. Пример разрешённого простого использования:
  
  

  print(i > 5 ? "big" : "small");

• Используемые художником или дизайнером счётчики должны начинаться с 0, как в обычных массивах в коде. Некоторые старые инструменты могут по-прежнему начинать с 1, но все новые разработанные для художников инструменты начинают с 0.
• При проверке существования указателя выполняйте эту операцию явным образом. Поэтому используйте if (myPointer != nullptr), а не if (myPointer).
• По возможности используйте RAII (Resource Acquisition Is Initialization). То есть вместо создания отдельной функции initialise() полностью инициализируйте класс в его конструкторе, чтобы он никогда не был в незавершённом состоянии.
• Пишите конструктор и деструктор одновременно: пишите каждый соответствующий delete для каждого new, чтобы не забыть о них позже.
• Если вы пишете временный отладочный код, то добавьте к нему комментарий с QQQ. Никогда не делайте коммит с QQQ: удаляйте весь отладочный код перед коммитом.
• Если хотите оставить пометку о том, что нужно сделать позже, используйте QQToDo. Если это нужно будет сделать вам, до добавьте к комментарию свою букву, например, QQToDoJ. Делайте коммиты с QQToDo только если непрактично завершать работу сейчас.
• Определения классов начинаются со всех функций, затем идут все переменные. Порядок должен быть следующим: public/protected/private. Это может иногда означать, что вам потребуется использовать одни и те же ключевые слова public/protected/private в одном файле заголовка несколько раз (сначала для функций, потом для переменных).
• Класс начинается с его конструкторов, за которым идёт деструктор. Если они private или protected, то всё равно должны находиться наверху.
• Если что-то имеет два варианта, но не точно true/false, то лучше использовать класс enum, а не boolean. Например, для указания направления не используйте bool isRight. Вместо этого применяйте enum Direction со значениями Left и Right.
• Вместо std::string и std::stringstream используйте наши собственные классы RString, RStringstream, WString и WStringstream (они привязаны к нашей собственной системе управления памятью).
• Переменная float time всегда означает время после последнего кадра в секундах. Если time значит что-то другое, то выразите это явным образом, например, дав название timeExisting.
• Убедитесь, что весь код независим от частоты кадров, поэтому активно используйте для этого переменную float time.
• Делайте структуры явными и понятными. Например, избегайте подобного:
  
  

  if (yellow)
  {
      return banana;
  }
  return kiwi;

  
  Здесь подразумевается, что в зависимости от yellow возвращается banana или kiwi. Более читаемым код будет, если выразить это явно:
  
  

  if (yellow)
  {
      return banana;
  }
  else
  {
      return kiwi;
  }

• Используйте nullptr, а не NULL.
• Мы используем auto только для таких случаев, как сложные типы итераторов. Для всего остального мы указываем тип явным образом.
• Используйте там, где это применимо, range-based for, например:
  
  

  for (const Banana& ultimateFruit : myList)

  
  (Учтите, что когда вы не работаете с указателями, важно типизировать эту ссылку, потому что иначе в этом случае Banana будет скопирована.)
• По мере применимости используйте override и final.
• Если функция виртуальная, то к ней всегда нужно добавлять ключевое слово virtual, не только в родительском классе, но и в каждой из версий функций в классах-потомках.
• Используйте enum со строгой типизацией, то же самое со словом class. Регистр в названиях такой же, как в классах. Например:
  
  

  enum class Fruit
  {
      Banana,
      Kiwi,
      ApplePie
  };

• Используйте rvalue-ссылки (&&), если только это совершенно необходимо.
• По возможности используйте unique_ptr. Если объект не имеет владельца, то он хранится как обычный указатель.
• Избегайте создания экземпляров сложных типов в списке инициализации. В списке инициализации используется простое копирование и назначение, а более сложный код, например вызов new, должен находиться в теле конструктора. Вот пример того, как это работает:
  
  

  FruitManager::FruitManager(Kiwi* notMyFruit):
      notMyFruit(notMyFruit)
  {
      bestFruitOwnedHere.reset(new Banana());
  }

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

  unique_ptr

  .
• Лямбда-функции, которые слишком длинны для записи в одну строку, должны иметь следующие отступы:
  
  

  auto it = std::find_if(myVec.begin(),
                         myVec.end(),
                         [id = 42] (const Element& e)
                         { 
                             return e.id() == id;
                         });

• Не пользуйтесь MyConstructor = delete (похоже, что это не поддерживается в некоторых используемых нами компиляторах).
• Не используйте возможности C++11 для инициализации списков (похоже, что это не поддерживается в некоторых используемых нами компиляторах). Поэтому мы не используем такого:
  
  

  std::vector<int> thingy = {1, 2, 3};

• Не используйте возможности, добавленные в C++14.

C#

• Переменные должны находиться в начале файла, а не внизу. Мы строго разделяем функции и переменные (как и в C++), поэтому сначала указываются все переменные, затем все функции.
• Названия async-функций всегда должны заканчиваться на Async, например, eatBananaAsync.