C++ Core Guidelines

Вольный перевод (скорее, изложение) https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md

P.1. Самокомментирующийся код

Лучший способ комментировать код - писать код, не нуждающийся в комментариях. Например, если мы создаём класс для работы с датой, предпочтителен вид:

class myDate {
  year_t year;
  month_t month;
  day_t day;
};

Кастомные типы кажутся бессмысленными в объявлении членов класса, но в параметрах методов и функций они будут явно указывать не только тип, но и назначение передаваемых данных, устраняя необходимость в комментировании параметров функции:

day_t period(myDate from, myDate to)