thevar1able/ClickHouse

Fork 0

mirror of https://github.com/ClickHouse/ClickHouse.git synced 2024-11-14 11:33:46 +00:00

BayoNet 48531bb5ee Fixed russian inclusions into english version of the document.

2018-01-19 17:36:40 +03:00

42 KiB

Raw Blame History

Как писать код на C++

Общее

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

Форматирование

Большую часть форматирования сделает автоматически clang-format.
Отступы - 4 пробела. Настройте среду разработки так, чтобы таб добавлял четыре пробела.

Открывающая фигурная скобка на новой, отдельной строке. (Закрывающая - тоже.)

inline void readBoolText(bool & x, ReadBuffer & buf)
{
    char tmp = '0';
    readChar(tmp, buf);
    x = tmp != '0';
}

Но если всё тело функции достаточно короткое (один statement) - при желании, его можно целиком разместить на одной строке. При этом, вокруг фигурных скобок ставятся пробелы (кроме пробела на конце строки).
```
inline size_t mask() const                { return buf_size() - 1; }
inline size_t place(HashValue x) const    { return x & mask(); }
```
Для функций, пробелы вокруг скобок не ставятся.
```
void reinsert(const Value & x)
```
```
memcpy(&buf[place_value], &x, sizeof(x));
```
При использовании выражений if, for, while, ... (в отличие от вызовов функций) перед открывающей скобкой ставится пробел.
```
for (size_t i = 0; i < rows; i += storage.index_granularity)
```

Вокруг бинарных операторов (+, -, *, /, %, ...), а также тернарного оператора ?: ставятся пробелы.

UInt16 year = (s[0] - '0') * 1000 + (s[1] - '0') * 100 + (s[2] - '0') * 10 + (s[3] - '0');
UInt8 month = (s[5] - '0') * 10 + (s[6] - '0');
UInt8 day = (s[8] - '0') * 10 + (s[9] - '0');

Если ставится перенос строки, то оператор пишется на новой строке, и перед ним увеличивается отступ.

if (elapsed_ns)
    message << " ("
         << rows_read_on_server * 1000000000 / elapsed_ns << " rows/s., "
        << bytes_read_on_server * 1000.0 / elapsed_ns << " MB/s.) ";

Внутри строки можно, при желании, выполнять выравнивание с помощью пробелов.

dst.ClickLogID         = click.LogID;
dst.ClickEventID       = click.EventID;
dst.ClickGoodEvent     = click.GoodEvent;

Вокруг операторов ., -> не ставятся пробелы.

При необходимости, оператор может быть перенесён на новую строку. В этом случае, перед ним увеличивается отступ.
Унарные операторы (--, ++, *, &, ...) не отделяются от аргумента пробелом.
После запятой ставится пробел, а перед - нет. Аналогично для точки с запятой внутри выражения for.
Оператор [] не отделяется пробелами.
В выражении template <...>, между template и < ставится пробел; после < и до > - не ставится.
```
template <typename TKey, typename TValue>
struct AggregatedStatElement
{}
```

В классах и структурах, public, private, protected пишется на том же уровне, что и class/struct, а все остальные внутренности - глубже.

template <typename T>
class MultiVersion
{
public:
    /// Version of object for usage. shared_ptr manage lifetime of version.
    using Version = std::shared_ptr<const T>;
    ...
}

Если на весь файл один namespace и кроме него ничего существенного нет - то отступ внутри namespace не нужен.
Если блок для выражения if, for, while... состоит из одного statement-а, то фигурные скобки писать не обязательно. Вместо этого поместите statement на отдельную строку. Этим statement-ом также может быть вложенный if, for, while... Но если внутренний statement содержит фигурные скобки или else, то внешний блок следует писать в фигурных скобках.
```
/// Finish write.
for (auto & stream : streams)
    stream.second->finalize();
```
Не должно быть пробелов на концах строк.
Исходники в кодировке UTF-8.
В строковых литералах можно использовать не-ASCII.
```
<< ", " << (timer.elapsed() / chunks_stats.hits) << " μsec/hit.";
```
Не пишите несколько выражений в одной строке.
Внутри функций, группируйте куски кода, отделяя их не более, чем одной пустой строкой.
Функции, классы, и т. п. отделяются друг от друга минимум одной, максимум двумя пустыми строками.
const (относящийся к значению) пишется до имени типа.
```
//correct
const char * pos
const std::string & s
//incorrect
char const * pos
```
При объявлении указателя или ссылки, символы * и & отделяются пробелами с обеих сторон.
```
//correct
const char * pos
//incorrect
const char* pos
const char *pos
```
При использовании шаблонных типов, пишите using (кроме, возможно, простейших случаев).

То есть, параметры шаблона указываются только в using и затем не повторяются в коде.

using может быть объявлен локально, например, внутри функции.
```
//correct
using FileStreams = std::map<std::string, std::shared_ptr<Stream>>;
FileStreams streams;
//incorrect
std::map<std::string, std::shared_ptr<Stream>> streams;
```
Нельзя объявлять несколько переменных разных типов в одном объявлении.
```
//incorrect
int x, *y;
```

C-style cast не используется.

//incorrect
std::cerr << (int)c <<; std::endl;
//correct
std::cerr << static_cast<int>(c) << std::endl;

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

Аналогично для маленьких методов в любых классах/структурах.

Для шаблонных классов/структур, лучше не отделять объявления методов от реализации (так как иначе они всё равно должны быть определены в той же единице трансляции).
Не обязательно умещать код по ширине в 80 символов. Можно в 140.
Всегда используйте префиксный инкремент/декремент, если постфиксный не нужен.
```
for (Names::const_iterator it = column_names.begin(); it != column_names.end(); ++it)
```

Необходимо обязательно писать комментарии во всех нетривиальных местах.

Это очень важно. При написании комментария, можно успеть понять, что код не нужен вообще, или что всё сделано неверно.
```
/** Part of piece of memory, that can be used.
  * For example, if internal_buffer is 1MB, and there was only 10 bytes loaded to buffer from file for reading,
  * then working_buffer will have size of only 10 bytes
  * (working_buffer.end() will point to position right after those 10 bytes available for read).
  */
```
Комментарии могут быть сколь угодно подробными.

Комментарии пишутся до соответствующего кода. В редких случаях - после, на той же строке.

/** Parses and executes the query.
*/
void executeQuery(
    ReadBuffer & istr, /// Where to read the query from (and data for INSERT, if applicable)
    WriteBuffer & ostr, /// Where to write the result
    Context & context, /// DB, tables, data types, engines, functions, aggregate functions...
    BlockInputStreamPtr & query_plan, /// Here could be written the description on how query was executed
    QueryProcessingStage::Enum stage = QueryProcessingStage::Complete /// Up to which stage process the SELECT query
    )

Комментарии следует писать только на английском языке.
При написании библиотеки, разместите подробный комментарий о том, что это такое, в самом главном заголовочном файле.
Нельзя писать комментарии, которые не дают дополнительной информации. В частности, нельзя писать пустые комментарии вроде этого:
```
/*
* Procedure Name:
* Original procedure name:
* Author:
* Date of creation:
* Dates of modification:
* Modification authors:
* Original file name:
* Purpose:
* Intent:
* Designation:
* Classes used:
* Constants:
* Local variables:
* Parameters:
* Date of creation:
* Purpose:
*/
```
(пример взят с ресурса http://home.tamk.fi/~jaalto/course/coding-style/doc/unmaintainable-code/
Нельзя писать мусорные комментарии (автор, дата создания...) в начале каждого файла.
Однострочные комментарии начинаются с трёх слешей: /// , многострочные с /**. Такие комментарии считаются «документирующими».

Замечание: такие комментарии могут использоваться для генерации документации с помощью Doxygen. Но, фактически, Doxygen не используется, так как для навигации по коду гораздо удобне использовать возможности IDE.
В начале и конце многострочного комментария, не должно быть пустых строк (кроме строки, на которой закрывается многострочный комментарий).
Для закомментированных кусков кода, используются обычные, не "документирующие" комментарии.
Удаляйте закомментированные куски кода перед коммитом.
Не нужно писать нецензурную брань в комментариях или коде.
Не пишите прописными буквами. Не используйте излишнее количество знаков препинания.
```
/// WHAT THE FAIL???
```
Не составляйте из комментариев строки-разделители.
```
///******************************************************
```
Не нужно писать в комментарии диалог (лучше сказать устно).
```
/// Why did you do this stuff?
```
Не нужно писать комментарий в конце блока о том, что представлял собой этот блок.
```
/// for
```

Имена

Имена переменных и членов класса - маленькими буквами с подчёркиванием.
```
size_t max_block_size;
```
Имена функций (методов) - camelCase с маленькой буквы.
```
std::string getName() const override { return "Memory"; }
```
Имена классов (структур) - CamelCase с большой буквы. Префиксы кроме I для интерфейсов - не используются.
```
class StorageMemory : public IStorage
```
Имена using-ов - также, как классов, либо можно добавить _t на конце.
Имена типов - параметров шаблонов: в простых случаях - T; T, U; T1, T2.

В более сложных случаях - либо также, как имена классов, либо можно добавить в начало букву T.
```
template <typename TKey, typename TValue>
struct AggregatedStatElement
```
Имена констант - параметров шаблонов: либо также, как имена переменных, либо N - в простом случае.
```
template <bool without_www>
struct ExtractDomain
```
Для абстрактных классов (интерфейсов) можно добавить в начало имени букву I.
```
class IBlockInputStream
```
Если переменная используется достаточно локально, то можно использовать короткое имя.

В остальных случаях - используйте достаточно подробное имя, описывающее смысл.
```
bool info_successfully_loaded = false;
```
define-ы - ALL_CAPS с подчёркиванием. Глобальные константы - тоже.
```
#define MAX_SRC_TABLE_NAMES_TO_STORE 1000
```
Имена файлов с кодом называйте по стилю соответственно тому, что в них находится.

Если в файле находится один класс - назовите файл, как класс - в CamelCase.

Если в файле находится одна функция - назовите файл, как функцию - в camelCase.
Если имя содержит сокращение, то:
- для имён переменных, всё сокращение пишется маленькими буквами mysql_connection (не mySQL_connection).
- для имён классов и функций, сохраняются большие буквы в сокращении MySQLConnection (не MySqlConnection).
Параметры конструктора, использующиеся сразу же для инициализации соответствующих членов класса, следует назвать также, как и члены класса, добавив подчёркивание в конец.
```
FileQueueProcessor(
    const std::string & path_,
    const std::string & prefix_,
    std::shared_ptr<FileHandler> handler_)
    : path(path_),
    prefix(prefix_),
    handler(handler_),
    log(&Logger::get("FileQueueProcessor"))
{
}
```
Также можно называть параметры конструктора так же, как и члены класса (не добавлять подчёркивание), но только если этот параметр не используется в теле конструктора.
Именование локальных переменных и членов класса никак не отличается (никакие префиксы не нужны).
```
timer (not m_timer)
```
Константы в enum-е - CamelCase с большой буквы. Также допустимо ALL_CAPS. Если enum не локален, то используйте enum class.
```
enum class CompressionMethod
{
    QuickLZ = 0,
    LZ4     = 1,
};
```
Все имена - по английски. Транслит с русского использовать нельзя.
```
не Stroka
```
Сокращения (из нескольких букв разных слов) в именах можно использовать только если они являются общепринятыми (если для сокращения можно найти расшифровку в английской википедии или сделав поисковый запрос).

AST, SQL.

Не NVDH (что-то неведомое)

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

Впрочем, сокращения также можно использовать, если расшифровка находится рядом в комментарии.
Имена файлов с исходниками на C++ должны иметь расширение только .cpp. Заголовочные файлы - только .h.