Комментарии в коде. За и почему не против 28.05.2017

По поводу комментариев в коде существуют две точки зрения. Первая говорит, что нужно комментировать как минимум сложные и запутанные места. Вторая — комментарии излишни, комментарии врут, запутанный код нужно переписать так, чтобы он сам говорил за себя.

У второй точки зрения поклонников очевидно больше. Книги пестрят советами по именованию переменных, классов и методов, стилю написания кода и т.д. Неудивительно, что большинство готово маршировать под лозунгом «Хороший код не нуждается в комментариях!».

Да, действительно, хороший код не нуждается в комментариях. К сожалению, код действительно хорошим бывает не всегда. С какими проблемы могут помешать нам написать хороший код?

К сожалению, мы все не идеальны. Решение пришедшее программисту на ум, кажется ему очевидным, а код его реализующий очевидно хорошим, т.к. код, реализующий очевидное хорош, а ,следовательно, не должен требовать комментариев. Однако, чаще всего такая точка зрения оказывается субъективной, а сам код — нетривиальным.

Большинство авторов книг по программированию — англоязычны. А это значит, что именование переменных, будь то в терминах задачи или решения, для них является более легкой задачей нежели для программистов, не владеющих беглым английским языком. О какой читаемости кода может идти речь, если в сложных случаях такой программист просто не способен выбрать именование переменных так, как это сделал бы носитель языка?

В общем, если вы не уверены, что ваш код тривиален или однозначен, оставьте пояснение, и будущее поколение будет вам благодарно.

by 28.05.2017