Хороший код не нужно объяснять

Хороший код
не нужно объяснять.

Как хорошую шутку.
Если её приходится растолковывать,
она уже не смешная.

Если код приходится растолковывать,
он уже не хороший.

Комментарий,
который спасает запутанную функцию,
не спасает её.
Он просто признаёт,
что она запуталась.

Сначала — понятное имя.
Потом — простой путь.
И только если без этого никак —
комментарий,
объясняющий «почему»,
а не «что».

«Что» должен говорить сам код.

Умная строчка
радует автора.
Понятная строчка
служит всем,
кто придёт потом.

А потом почти всегда
приходишь ты сам,
через полгода,
уже не помня
ни одного своего трюка.

Пиши так,
чтобы объяснять
не пришлось.

– Serguey Asael Shinder