Простые, но эффективные протоколы, которым вы сможете следовать в 2021 году
«Код никогда не лжет, иногда лгут комментарии». - Рон Джеффрис
Комментирование кода! Некоторые люди говорят, что это некрасиво, некоторые говорят, что это нормальная и хорошая практика.
Комментирование - это «искусство» описания того, что ваша программа будет делать, с помощью операторов «высокого уровня» на английском языке.
Здесь я перечислил 4 простых протокола, которым нужно следовать при написании комментариев.
Хотя эти предложения можно применить к любому языку программирования, мы будем использовать JavaScript, чтобы проиллюстрировать их на практике.
1. Комментируйте только те элементы, которые имеют сложную бизнес-логику.
«Комментарии - это извинение, а не требование. Хороший код в основном документирует сам.
Ниже один выглядит хреново.
function hashIt(data) { // The hash let hash = 0; // Length of string const length = data.length; // Loop through every character in data for (let i = 0; i < length; i++) { // Get character code. const char = data.charCodeAt(i); // Make the hash hash = (hash << 5) - hash + char; // Convert to 32-bit integer hash &= hash; } }
Намного лучше
function hashIt(data) { let hash = 0; const length = data.length; for (let i = 0; i < length; i++) { const char = data.charCodeAt(i); hash = (hash << 5) - hash + char; // Convert to 32-bit integer hash &= hash; } }
2. Удалить мертвый код.
Контроль версий существует не просто так. Оставьте старый код в своей истории.
doStuff(); // doOtherStuff(); // doSomeMoreStuff(); // doSoMuchStuff();
Вместо
doStuff();
3. Удалите комментарии из журнала, вот что Git logs are for
Помните, используйте контроль версий! Нет необходимости в мертвом коде, закомментированном коде и особенно в журнальных комментариях. Используйте git log
, чтобы получить историю!
/** * 2016-12-20: Removed monads, didn't understand them (RM) * 2016-10-01: Improved using special monads (JP) * 2016-02-03: Removed type-checking (LI) * 2015-03-14: Added combine with type-checking (JR) */ function combine(a, b) { return a + b; }
Так может хорошо выглядеть. Очевидно!
function combine(a, b) { return a + b; }
4. Позиционные маркеры? Удалить их
Обычно они просто добавляют шума. Пусть имена функций и переменных вместе с правильным отступом и форматированием придают визуальную структуру вашему коду.
Полный беспорядок
//////////////////////////////////////////////////////////////////////////////// // Scope Model Instantiation //////////////////////////////////////////////////////////////////////////////// $scope.model = { menu: "foo", nav: "bar" }; //////////////////////////////////////////////////////////////////////////////// // Action setup //////////////////////////////////////////////////////////////////////////////// const actions = function() { // ... };
А теперь давайте немного приберемся
$scope.model = { menu: "foo", nav: "bar" }; const actions = function() { // ... };
Это письмо было вдохновлено репо на GitHub.