Можно ли написать хороший и понятный код без каких-либо комментариев?

Question

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

Answer 1

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

Самая большая проблема с комментариями - нет возможности проверить их точность. Я склонен согласиться с дядей Бобом Мартином в главе 4 его книги Чистый код :

Правильное использование комментариев должно компенсировать нашу неспособность выразить себя в код. Обратите внимание, что я использовал слово сбой. Я имел в виду это. Комментарии всегда неудачи. Мы должны иметь их, потому что мы не всегда можем понять, как выразить себя без них, но их использование не повод для праздника.

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

Большинство комментариев либо излишняя избыточность, либо прямая ошибка, либо опора, используемая для объяснения плохо написанного кода. Я говорю большинство , потому что есть определенные сценарии, в которых отсутствие выразительности связано с языком, а не с программистом.

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

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

Answer 2

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

Answer 3

Обычно вы можете превратить ваш комментарий в имя функции, например:

if (starColourIsGreaterThanThreshold(){
    doSomething(); 
}

....

private boolean starColourIsGreaterThanThreshold() { 
    return starColour.red > THRESHOLD && 
           starColour.blue > THRESHOLD && 
           starColour.green > THRESHOLD
} 

Answer 4

Используйте описательные имена переменных и имена описательных методов. Используйте пробелы.

Сделайте так, чтобы ваш код читался как обычный разговор.

Сравните использование Matchers в Junit:

assertThat(x, is(3));
assertThat(x, is(not(4)));
assertThat(responseString, either(containsString("color")).or(containsString("colour")));
assertThat(myList, hasItem("3"));

с традиционным стилем assertEquals:

assertEquals(3, x);

Когда я смотрю на оператор assertEquals, неясно, какой параметр является «ожидаемым», а какой «действительным».

Когда я смотрю на assertThat(x, is(3)), я могу прочитать это по-английски как "Утвердите, что х равен 3", что мне очень ясно.

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

if( (x < 3 || x > 17) && (y < 8 || y > 15) )

становится

if( xAndYAreValid( x, y ) )  // or similar...

Answer 5

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

account.updateBalance();
child.givePacifier();
int count = question.getAnswerCount();

Используйте enum s свободно. С enum вы можете заменить большинство boolean s и интегральных констант. Например:

public void dumpStackPretty(boolean allThreads) {
    ....
}

public void someMethod() {
    dumpStackPretty(true);
}

против

public enum WhichThreads { All, NonDaemon, None; }
public void dumpStackPretty(WhichThreads whichThreads) {
    ....
}

public void someMethod() {
    dumpStackPretty(WhichThreads.All);
}

Answer 6

Описательные имена - ваша очевидная первая ставка.

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

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

Для расчета корреляции вам также необходимо среднее значение и стандартное отклонение. Таким образом, у меня было два частных метода (ну, на самом деле, в этом случае они были общедоступными, поскольку их можно было использовать для других целей (но при условии, что они не могли бы быть частными)) для вычисления A) среднего значения, B) стандартного отклонения.

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

Как вы решаете, где разбить методы. Мой способ, если имя очевидно, например getAddressFromPage это правильный размер. Если у вас есть несколько претендентов, вы, вероятно, пытаетесь сделать слишком много, если вы не можете придумать название, которое имеет смысл, ваш метод может «не делать» достаточно, хотя последнее гораздо менее вероятно.

Answer 7

Я считаю, что это возможно, если учесть тот факт, что не всем нравится один и тот же стиль. Таким образом, чтобы свести к минимуму комментарии, знание ваших «читателей» является самым важным.

В программном обеспечении типа «информационные системы» попробуйте использовать декларативное предложение, попытайтесь приблизить строку кода к строке на английском языке и избегайте «математического программирования» (с i, j и k для индекса и -линерум-делать-много) любой ценой.

Answer 8

Я действительно не думаю, что комментарии являются хорошей идеей в большинстве случаев. Комментарии не проверяются компилятором, поэтому они часто вводят в заблуждение или ошибочны, так как код со временем меняется. Вместо этого я предпочитаю самодокументированные, сжатые методы, которые не нуждаются в комментариях. Это может быть сделано, и я делал это таким образом в течение многих лет.

Написание кода без комментариев требует практики и дисциплины, но я считаю, что дисциплина окупается по мере развития кода.

Answer 9

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

Подумайте о специальных структурах данных. Если бы все, что компьютерные ученые когда-либо публиковали о структурах данных, были хорошо написанным кодом, немногие действительно могли бы понять относительное преимущество одной структуры данных над другой - потому что время выполнения Big-O любой операции иногда просто не очевидно из чтения кода , Вот тут и вступают математические и амортизированные анализы, представленные в статьях.

Answer 10

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

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

Другое место, где я нахожу комментарии полезными и важными, - убедиться, что кто-то не заменяет код чем-то, что выглядит так, как будто оно должно работать, но не будет. В этом случае я оставляю неверный код и комментирую его, объясняя, почему он не должен использоваться.

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

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