Нужно ли комментировать код?

Раньше, 10+ лет назад, комментирование кода считалось правилом хорошего тона. Это делало код более понятным для читателей.

Последнее десятилетие сложилась концепция «чистого кода» по одноименной книге Роберта Мартина, согласно которой код нужно писать таким образом, чтобы он был понятен людям, которые его читают, без комментариев. Если код нуждается в комментировании — значит, он непонятно написан.

Это как с iPhone. Он с самого начала своего существования продавался без инструкции. Была такая концепция — сделать телефон сразу понятным. То же самое и с кодом.

Единственное исключение — это комментирование кода для автоматически генерируемой документации (API Reference), которая бывает в ряде проектов и используется, скорее, для целей проектирования, а не программирования.