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

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

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

Часто при разработке мы сталкиваемся с проектами, загроможденными комментариями, описывающими чуть ли не каждую строчку кода. Этой практике часто учат и поощряют в UNI или колледже. Однако является ли это наиболее эффективным способом общения?

Помогает ли нам донести сообщение добавление информации над нашими функциями и переменными?

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

«Программирование — это искусство рассказывать другому человеку, что он хочет от компьютера». - Дональд Кнут

Давайте рассмотрим несколько основных сценариев.

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

// this function deletes a banana
function remove() { }
// sends username and password of the admin to the create user api function createNew(id, pass) { }

Давайте улучшим имена переменных.

// this function deletes a banana
function deleteBanana() { }
// sends username and password of the admin to the create user api function createAdminUser(username, password) { }

Теперь, когда код имеет осмысленные имена переменных, помогают ли эти комментарии читателю понять код?

Комментарии такого типа не нужны и требуют дополнительных умственных способностей при расшифровке кода.

Здесь у нас те же функции без комментариев.

function deleteBanana() { }
function createAdminUser(username, password) { }

Что делает deleteBanana? Он удаляет банан... очевидно!
Что делает createAdminUser? Он создает пользователя-администратора! 😝
Если имя переменной имеет смысл вне контекста кода, это хорошее имя.

«Код — это как юмор.
Когда вам приходится что-то объяснять, это плохо». -Кори Хаус

Растет использование удобных библиотек для создания комментариев; к сожалению, они также дублируют информацию и увеличивают непоследовательность.

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

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

// Deletes the Fruit entity with the specified fruitId.
function deleteFruit(int fruitId) { }
// The class definition for the FruitBowl entity.
class FruitBowl {
    // The Banana of the FruitBowl entity.
    static banana
}
// Creates the Admin User entity.
function createAdminUser() { }

Здесь разработчик изменил функционал, но забыл обновить описание. Возможно, новая функция может создать любого типа пользователя. Однако в комментарии утверждается, что он создает пользователей-администраторов. Что правильно?

// Creates the Admin User entity.
function createUser(userRole) { }

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

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

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

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

Старайтесь писать только то, что требуется читателю для понимания кода.

Спасибо за то, что вы здесь! Удачного кодирования! ☺️

Первоначально опубликовано на https://www.jasperdunn.com 27 марта 2021 г.