Выражайте идеи непосредственно в коде

Причина

Компиляторы не читают комментарии (и проектную документацию), как и многие программисты (последовательно). То, что выражено в коде, имеет определённую семантику и может (в принципе) быть проверено компиляторами и другими инструментами.

Пример

class Date {
public:
    Month month() const;  // правильно
    int month();          // неправильно
    // ...
};

Первое объявление month явно указывает на возврат Month и на отсутствие изменения состояния объекта Date. Второй вариант оставляет читателя в догадках и открывает больше возможностей для необнаруженных ошибок.

Пример (плохой)

Этот цикл является ограниченной формой std::find:

void f(vector<string>& v)
{
    string val;
    cin >> val;
    // ...
    int index = -1;                    // плохо, плюс следует использовать gsl::index
    for (int i = 0; i < v.size(); ++i) {
        if (v[i] == val) {
            index = i;
            break;
        }
    }
    // ...
}

Пример (хороший)

Намного более ясным выражением намерения было бы:

void f(vector<string>& v)
{
    string val;
    cin >> val;
    // ...
    auto p = find(begin(v), end(v), val);  // лучше
    // ...
}

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

Программист на C++ должен знать основы стандартной библиотеки и использовать её там, где это уместно. Любой программист должен знать основы используемых им базовых библиотек проекта и использовать их надлежащим образом. Используя эти руководящие принципы, смотрите библиотеку поддержки.

Примечание

Выражать идеи непосредственно в коде включает в себя:

• Использование соответствующих (а не только работающих) стандартных алгоритмов
• Использование типов для описания инвариантов (а не просто использование int для флагов)
• Использование constexpr для вычислений, которые должны выполняться во время компиляции, а не const переменных, инициализируемых во время выполнения
• Указание ненулевых указателей как not_null

Контроль

Сложно механически проверить. Возможности:

• Искать приведение (int) — предпочитайте именованные приведения
• Искать void* — предпочитайте шаблоны или варианты