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

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

ОТВЕТЫ

Ответ 1

Прочитайте Code Complete, 2nd Edition для обложки. Возможно, дважды.

Чтобы дать некоторые особенности:

  • Выполнение кода для чтения
  • Устранение повторения кода
  • Выполнение дизайна/архитектуры перед написанием кода

Ответ 2

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

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

Ответ 3

Мне нравится код "humanise", поэтому вместо:

if (starColour.red > 200 && starColour.blue > 200 && starColour.green > 200){
   doSomething();
}

Я сделаю это:

bool starIsBright;
starIsBright = (starColour.red > 200 && starColour.blue > 200 && starColour.green > 200);

if(starIsBright){
   doSomething();
}

Ответ 4

В некоторых случаях - да, но во многих случаях нет. Части Да уже отвечают другие - сохраняйте их простыми, красиво пишете, дайте им читаемые имена и т.д. Часть Нет, когда проблема, которую вы решаете в коде это вовсе не проблема с кодом, а скорее проблема с конкретной областью или проблема бизнес-логики. У меня нет проблем с чтением паршивого кода, даже если у него нет комментариев. Это раздражает, но выполнимо. Но практически невозможно прочитать какой-то код, не понимая, почему это так и что он пытается решить. Итак, такие вещи, как:

if (starColour.red > 200 && starColour.blue > 200 && starColour.green > 200){
   doSomething();
}

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

// we do this according to the requirement #xxxx blah-blah..
if (starColour.red > 200 && starColour.blue > 200 && starColour.green > 200){
   doSomething();
}

Ответ 5

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

Ответ 6

Если вы действительно этого хотите, вам нужно будет очень подробно описать имена и имена переменных.

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

Ответ 7

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

Просто потому, что функция очень понятна в объяснении того, что она делает, сама по себе не говорит вам, почему она делает то, что она делает.

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

Ответ 8

Я считаю, что концепция Fluent Interfaces действительно является хорошим примером этого.

var bob = DB.GetCustomers(). FromCountry ( "США" ). WithName ( "Bob" )

Ответ 9

Clean Code от Robert C. Martin содержит все необходимое для написания чистого, понятного кода.

Ответ 10

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

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

Контрастность использования совпадений в 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)), я могу прочитать это на английском языке как "Assert that x is 3", что очень ясно для меня.

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

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

становится

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

Ответ 11

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

Ответ 12

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

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

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

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

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

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

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

Ответ 13

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

if (starColourIsGreaterThanThreshold(){
    doSomething(); 
}

....

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

Ответ 14

Я думаю, что комментарии должны объяснять, почему, возможно, что, но, насколько это возможно, код должен определять, как (поведение).

Кто-то должен уметь читать код и понимать, что он делает (как) с кодом. Что может быть неочевидным, так это то, почему вы хотели бы такого поведения и какое это поведение вносит общие требования.

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

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

Ответ 15

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

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

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

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);
}

Ответ 16

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

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

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

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

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

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

Ответ 17

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

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

Ответ 18

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

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

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

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

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

Ответ 19

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

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

Ответ 20

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

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