Документация и комментарии служат аналогичной цели. Речь идет об общении с другими разработчиками сейчас, с другими разработчиками в будущем, а также с самим собой в будущем.

Когда я говорю о комментариях, я не имею в виду комментарии, используемые для документирования API, функций, классов или модулей. Это не совсем комментарии, а скорее встроенная документация.

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


Комментарии

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

Часто они констатируют только очевидное, и это только загромождает код.

#loop through the values to be checked
while i <= maxNum:
    [...]
Войти в полноэкранный режим

Выйти из полноэкранного режима

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


Не используйте комментарии без необходимости

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

let price = 0; // price in cents
Войти в полноэкранный режим

Выйти из полноэкранного режима

против

let priceInCents = 0;
Войти в полноэкранный режим

Выйти из полноэкранного режима

Часто комментарии используются для структурирования кода. Для структуры у нас есть лучшие инструменты, которые никогда не лгут.

function processInput(input: string) {  
    // validate input  
    if (input.length < 10) {  
        throw "input too short"  
    }  
    if (input.length > 100) {  
        throw "input too long"  
    }  

    // remove colors  
    let result  = input.replace('red', '').replace('green', '').replace('blue', '');  

    // format result  
    result = result.trim().toUpperCase()  

    return result  
}
Войти в полноэкранный режим

Выйти из полноэкранного режима

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

function processInput(input: string) {  
    validateInput(input);  

    let result = removeColors(input);  

    return formatResult(input)  
}

function validateInput(input: string) {  
    if (input.length < 10) {  
        throw "input too short"  
    }  
    if (input.length > 100) {  
        throw "input too long"  
    }
}

function removeColors(input: string) {  
    return input.replace('red', '').replace('green', '').replace('blue', '');  
}  

function formatResult(result: string) {  
    return result.trim().toUpperCase();  
}
Войти в полноэкранный режим

Выйти из полноэкранного режима

Приведенный выше код очень четко показывает 3 обязанности processInput функция. проверить, сделать и вернуть отформатированный. Я не хочу подчеркивать, что вы всегда должны структурировать свои функции таким образом. Часто наличие проверки внутри «материнской» функции является хорошей идеей, чтобы точно показать, что происходит. Но когда вы чувствуете желание написать комментарий к структурированному коду, подумайте об использовании функции для структурирования.


Используйте комментарии, чтобы объяснить почему, странности и последствия

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


почему

// we are moving between API's so we are calling new and old apis.
oldUsersApi.updateData(userData);
newUserApi.updateData(userData);
Войти в полноэкранный режим

Выйти из полноэкранного режима


странный

// this is odd but the 3rd party client api enforces us to disconnect before we can connect
client.disconnect()
client.connect()
Войти в полноэкранный режим

Выйти из полноэкранного режима


последствия

user.delete() // deleting the user will cascade deletion of all their data
Войти в полноэкранный режим

Выйти из полноэкранного режима


Мои рекомендации по правильному комментированию кода

  • Комментируйте только почему и только если это не очевидно
  • Всегда старайтесь сначала объяснить себя в коде.
  • Использовать как объяснение намерений.
  • Используйте в качестве разъяснения кода.
  • Используйте как предупреждение о последствиях.

Эта статья взята из серии моих лекций.

Разговор о принципах разработки программного обеспечения и чистом коде

фавикон
Slideshare.net