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

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

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

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

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

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

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

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

Read Code Complete, 2nd Edition cover to cover. Perhaps twice.

To give some specifics:

• Making code readable
• Eliminating code repetition
• Doing design/architecture before you write code

Descriptive names is your obvious first bet.

Secondly make sure each method does one thing and only one thing. If you have a public method that needs to do many things, split it up into several private methods and call those from the public method, in a way that makes the logic obvious.

Some time ago I had to create a method that calculated the correlation of two time series.

To calculate the correlation you also need the mean and standard deviation. So I had two private methods (well actually in this case they were public as they could be used for other purposes (but assuming they couldn't then they would be private)) for calculating A) the mean, B) the standard deviation.

This sort of splitting up of function into the smallest part that makes sense is probably the most important thing to make a code readable.

How do you decide where to break up methods. My way is, if the name is obvious e.g. getAddressFromPage it is the right size. If you have several contenders you are probably trying to do too much, if you can't think of a name that makes sense you method may not "do" enough - although the latter is much less likely.

If you want to code entirely without comments and still have your code be followable, then you'll have to write a larger number of shorter methods. Methods will have to have descriptive names. Variables will also have to have descriptive names. One common method of doing this is to give variables the name of nouns and to give methods the names of verbal phrases. For example:

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

Use enums liberally. With an enum, you can replace most booleans and integral constants. For example:

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

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

vs

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

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

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

Чистый код Роберта Мартина содержит все необходимое для написания понятного и понятного кода.

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

var bob = DB.GetCustomers (). FromCountry ("США"). WithName ("Боб")

Мне нравится «гуманизировать» код, поэтому вместо:

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

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

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

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

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

Use descriptive variable names and descriptive method names. Use whitespace.

Make your code read like normal conversation.

Contrast the use of Matchers in Junit:

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

with the traditional style of assertEquals:

assertEquals(3, x);

When I look at the assertEquals statement, it is not clear which parameter is "expected" and which is "actual".

When I look at assertThat(x, is(3)) I can read that in English as "Assert that x is 3" which is very clear to me.

Another key to writing self-documenting code is to wrap any bit of logic that is not clear in a method call with a clear name.

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

becomes

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

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

Самая большая проблема с комментариями - нет способа проверить их точность. Я склонен согласиться с дядей Бобом Мартином в главе 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();
}

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

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

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

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

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

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

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

if (starColourIsGreaterThanThreshold(){
    doSomething(); 
}

....

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

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

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

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

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