Не комментируйте свой код

Перевод: Nada Elokaily — Don’t comment your code

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

Я не говорю, что все комментарии бесполезны. При правильном использовании комментарии они могут быть очень полезны, но они не являются решением для устранения беспорядка в коде, более того они могут создать еще больше беспорядка.
Код может блестяще решать критическую проблему, используя хорошо продуманный алгоритм, известный шаблон проектирования или используя революционную особенность языка программирования, при этом он так же может зависеть от комментариев на каждом этапе пути его создания, и при этом оставаться трудно читаемым для команды разработчиков, поддерживающих его. Почему такое можем происходить?!
Некоторые разработчики склонны больше сосредотачиваться на написание лишних комментариев, чем на рефакторинге самого кода. Вот несколько примеров комментариев, без которых вашей команде будет лучше:

Избыточные комментарии

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

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

 // The processor delay for this component.
 protected int processorDelay = -1;

Комментарии вводящие в заблуждение

Благими намерениями вымощена дорога в ад. Автор кода в какой то момент может оставить неточный комментарий, по каким то естественным причинам (например после рефакторинга комментарий не будет соответствовать коду), и это будет стоить другому программисту дорогостоящее время отладки.

Например, здесь в комментарии написано, что метод выполняет return, когда this.closed имеет значение true и вызывает исключение когда тайм-аута истекает. Но в коде происходит следующее, если this.closed имеет значение false вначале ожидается тайм-аута и только затем, если только this.closed все еще false выдается исключение. Это может имеет определяющее значение!

// Returns when this.closed is true. Throws an exception on timeout is reached.
public synchronized void waitForClose(final long timeoutMillis) throws Exception
{
    if(!closed){
        wait(timeoutMillis);
        if(!closed)
            throw new Exception("MockResponseSender could not be closed");
    }
}

Обязательные комментарии

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

Так например здесь комментарии в формате jsdocs создает больше беспорядка, чем чего то полезного.

/**
 * @param title The title of the CD
 * @param author The author of the CD
 */ public void addCD(String title, String author) {
     CD cd = new CD();
     cd.title = title;
     cd.author = author;
     cdList.add(cd);
 }

Шумовые комментарии

Комментарии должны содержать новую информацию, иначе они будут просто шумом, который мы в итоге будем игнорировать. Если вы проигнорируете комментарий, значит, он был вообще бесполезным и его не должно было быть.

Так например автор этого комментария не только написал ненужный комментарий, но и забыл добавить код в тело catch и оставил невнятный комментарий без контекста.

try
{
     // Continue normal flow
     doSomething();
}
catch(Exception e1)
{
     // Give me a break!
}

Комментарии к замене функции или переменной

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

// does the module from the global list <mod> depend on the
// subsystem we are part of?
if (smodule.getDependSubsystems().contains(subSysMod.getSubSystem())) { }

Этот код не нуждается в комментарии, он нуждается в рефакторинге для его упрощения.

ArrayList moduleDependees = smodule.getDependSubsystems();
String ourSubSystem = subSysMod.getSubSystem();
if (moduleDependees.contains(ourSubSystem)) { }

Комментарии выделения маркера позиции

Пометка определенной позиции комментарием редко бывает полезной; хотя конечно имеет смысл собирать определенные функции вместе под каким то маркером. Но я не вижу, насколько это полезно для каждой функции, в целом они могут создавать больше беспорядка, чем быть чем-то полезным.

Признайся, вы сами делали такое;)

// Actions //////////////////////////////////

Комментарии авторства

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

Закомментированный код

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

InputStreamResponse response = new InputStreamResponse();
response.setBody(formatter.getResultStream(), formatter.getByteCount());
// InputStream resultsStream = formatter.getResultStream();
// StreamReader reader = new StreamReader(resultsStream);
// response.setContent(reader.read(formatter.getByteCount()));

Неуместные комментарии

Комментарии должны описывать код, рядом с которым он находится. Между кодом и комментариями должна быть очевидная связь.

Не оставляйте нерелевантную или общесистемную информацию в контексте локального комментария. Комментарии в коде это не место для интересных исторических дискуссий или несущественных описаний деталей.

Источники

Эта статья основана на книге Robert C. Martin: Clean Code: A Handbook of Agile Software Craftsmanship. Настоятельно рекомендуется прочитать эту книгу, это замечательная книга реально может вам помочь научиться писать код лучше.