Написание кода включает в себя общение между вами, компьютером и другими людьми.
Когда мы пишем код, мы даем другому разработчику инструкции, описывающие, что мы хотим, чтобы компьютер делал.
Разработчик должен поставить себя на место авторов и понять их мысли. Для этого автор должен писать четко и ясно.
Часто при разработке мы сталкиваемся с проектами, загроможденными комментариями, описывающими чуть ли не каждую строчку кода. Этой практике часто учат и поощряют в 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 г.