C++ Core Guidelines
Материал из KONANlabs
Вольный перевод (скорее, изложение) 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)
По той же причине для простых задач лучше использовать методы стандартной библиотеки, чем изобретать велосипед - код становится на порядки более читаемым без потери (а скорее с приростом) производительности.