У Microsoft роз’яснили, як правильно писати коментарі в коді

Представник команди Microsoft Windows Реймонд Чен пояснив, як правильно писати коментарі в коді. За його словами, коментарі всередині тіла функції повинні стосуватися стану системи в момент «виконання» коментаря. Про це Чен написав у блозі розробників Windows.

Автор допису розкритикував програмістів, які в коментарі до коду описують, які він буде працювати за певних обставин. За словами Чена, кожен коментар має описувати, що відбувається, коли виконання досягає блоку коду, в якому воно знаходиться. Якщо ж розробник хоче розмістити коментар перед оператором «if», то йому потрібно структурувати його відповідно до стану програми до оператора «if».

Для кращого пояснення Реймонд Чен наводить приклад невдалого розміщення коментарів:

// Widget is already vibrating, so we update the waveform in place.
// Else the waveform parameters will be set when we start vibrating.
if (waveformParameters != null) {
    waveformParameters.Shape = WaveformShape.Square;
    widget.UpdateWaveformParameters(waveformParameters);
}

Чен пише, що коли він побачив цей коментар, то зрозумів його так, ніби він свідчить про те, що віджет вже вібрує. «Я подумав: «Звідки мені знати, що він вібрує? Хіба нам не варто спочатку це перевірити?»

Потім, за його словами, він побачив частину коментаря else і ще більше заплутався, бо «навіщо ми говоримо про те, що ми робимо, якщо віджет не вібрує, якщо попереднє речення говорило нам, що ми (якимось чином) вже знаємо, що він вібрує?»

«Далі я бачу оператор if, і тепер він перевіряє, чи є щось null, що, я думаю, говорить нам, чи вібрує віджет. Але перше речення коментаря говорило, що ми знаємо, що він вібрує».

У підсумку Чен визнає, що коментар насправді описує те, що ми знаємо як правду, коли опинимося всередині блоку if. В якості альтернативи він пропонує менш заплутаний спосіб написання коментаря:

if (waveformParameters != null) {
    // Widget is already vibrating, so we update the waveform in place.
    waveformParameters.Shape = WaveformShape.Square;
    widget.UpdateWaveformParameters(waveformParameters);
} else {
    // Nothing to update right now. We will set the parameters
    // the next time we start vibrating.
}

Тут кожен коментар описує, що відбувається, коли виконання досягає блоку коду, в якому воно знаходиться. Автор навіть створив фіктивний блок else для зберігання пояснювального коментаря про те, чому нічого не робити – це нормально.

«Якщо ви дійсно хочете розмістити коментар перед оператором if, вам потрібно структурувати його відповідно до стану програми до оператора if.

// If the widget is already vibrating, then update the waveform in place.
// Else the waveform parameters will be set when we start vibrating.
if (waveformParameters != null) {
    waveformParameters.Shape = WaveformShape.Square;
    widget.UpdateWaveformParameters(waveformParameters);
}