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

Перевод статьи «Don’t comment your code», опубликованный сайтом webdevblog.ru.

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

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

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

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

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

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

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

 // 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()));

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

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

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

Источники

Эта статья основана на книге Роберта Мартина «Чистый код. Создание, анализ и рефакторинг». Настоятельно рекомендуется прочитать эту книгу, это замечательная книга реально может вам помочь научиться писать код лучше.

[customscript]techrocks_custom_after_post_html[/customscript]

[customscript]techrocks_custom_script[/customscript]