Написание качественного поддерживаемого кода: обзор комментариев

внешний интерфейс
Написание качественного поддерживаемого кода: обзор комментариев

Это 71-я оригинальная статья без воды.Если вы хотите получить больше оригинальных и хороших статей, выполните поиск в общедоступном аккаунте и подпишитесь на нас~ Эта статья была впервые опубликована в блоге Zhengcaiyun:Написание качественного поддерживаемого кода: обзор комментариев

предисловие

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

Интерпретация «комментариев» в языках программирования

Комментарии — это пояснения и описания кода. Комментарии — это пояснения или подсказки, данные разработчиками фрагменту кода при написании программы, что помогает улучшить читаемость программного кода. Комментарии не компилируются компьютером.

Хотите добавить заметку? Зачем комментировать?

Существование комментариев должно облегчить их вторичное чтение, обслуживание кода и передачу проекта. Он может лучше понимать код, что помогает повысить эффективность совместной работы и ускорить процесс разработки.

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

Так что комментарии еще надо добавить.

Основы

Горячие клавиши окна:ctrl+/макинтош:command+/

Классификация аннотаций

1. Комментарии в HTML

<div>
      这是一行文字
      <!-- 这是一行被注释的文字 -->
</div>

2. Комментарии в CSS

  • в .html файле
<style>
  div {
      /* color: #fff;  */
   }
</style>
  • в файле .css
div {
	/* color: #fff;  */
}
  • в файле .less или .scss
div {
	/* color: #fff;*/  /* 多行注释*/
	// font-size: 14px; // 单行注释
	background: #000;
}

3. Комментарии в JS

  • использование
    • Может использоваться для интерпретации кода JavaScript для повышения его читабельности.
    • Также может использоваться для предотвращения выполнения кода.
  • Однострочные комментарии (построчные комментарии) — начинаются с// начало. любой в//Текст после этого будет аннотирован
// 定义一个空数组
var ary = [];
var ary2 = []; // 又定义一个空数组
  • Многострочные комментарии (блочные комментарии) — начните с/*начинается с*/конец. любой в/*и*/Текст между ними аннотирован
/*
	这是多行注释
	定义一个数组
 */
var ary = [];
  • Используйте комментарии для предотвращения выполнения кода — закомментированный код JS не будет выполняться
//alert("123")  // 执行时未弹出该信息
alert("456")  // 执行时弹出该信息
  • аннотация функции
    • обычно с/**начинается с*/конец. любой в/**и*/Текст между ними аннотирован
/**
 * 提交
 *
 * @method onSubmit
 * @param {[Object]} 提交数据
 * @return  {[Bollean]}  [返回是否提交成功 ]
 */
const onSubmit = (params = {}) => {
  const result = false;
    if (params) {
			result = true;
		}
	return result;
};

В-четвертых, специальная пометка аннотации

  • **TODO **В этом комментарии должен быть написан код функции, а реализуемая функция будет кратко объяснена в описании.
  • FIXMEКод в этом комментарии нужно исправить, даже если код неверный и не может работать, его нужно исправить, как это исправить будет кратко объяснено в описании
  • **XXX ** Несмотря на то, что код в этом комментарии выполнил функцию, метод реализации все еще обсуждается. Я надеюсь, что в будущем его можно будет улучшить. Области, которые необходимо улучшить, будут кратко объяснены в описании.
  • **ПРИМЕЧАНИЕ.** Объясните, как работает код в этом комментарии.
  • **ВЗЛОМ **Комментарий плохо написан или неправильно отформатирован, необходимо настроить программный код под свои нужды
  • **ОШИБКА** В этом комментарии обнаружена ошибка
// TODO功能未完成,待完善
// FIXME  待修复
// XXX    实现方法待确认
// NOTE   代码功能说明
// HACK   此处写法有待优化
// BUG    此处有 Bug
const arr = []

Советы:

  • Почему//Аннотации можно использовать в файлах .less или .scss, но нельзя использовать в файлах .html и .css?
    • существуетMDNТолько о комментариях CSS/* */грамматика. Но синтаксис поддержки комментариев в LESS и SCSS такой же, как и в JS, с однострочными комментариями.// и многострочные комментарии/* */ два вида. Однострочные комментарии не сохраняются после компиляции.
  • Почему однострочные комментарии иногда пишут над кодом, а иногда после кода?
    • Комментарии можно писать в любом месте кода. Личное понимание, как правило, написанное над кодом означает комментарий к следующему коду, а написанное в конце кода означает комментарий к текущей строке кода.

Спецификация написания аннотации

  • комментарии к файлам
    • Расположенный в заголовке файла, он обычно содержит сводку, автора, информацию об изменении версии и время модификации.
  /*
   * 简述当前文件功能
   * @author 作者名称
   * @version 版本号 最近编辑时间
   * @description 该版本改动信息
   */
  • однострочный комментарий
    • всегда в//оставить пробел после
  // 这是一行注释
  • многострочный комментарий
    • Всегда держите звездочку вертикально выровненной (с пробелом перед конечным символом)
    • Не пишите комментарии в строке, где расположены начальный и конечный символы
    • Попробуйте использовать однострочные комментарии вместо многострочных.
    • При аннотировании функций рекомендуется использовать многострочные комментарии
  /*
    这里有一行注释
    这里有一行注释
    这里有一行注释
   */
  • аннотация функции
    • Каждая строка начинается с*начинается с первой строки первого*выровнять
    • Примечания и*оставить место
    • Комментарии к этикетке обязательны. пример:
/**
* 方法说明
* @method 方法名
* @for 所属类名
* @param {参数类型} 参数名 参数说明
* @return {返回值类型} 返回值说明
*/

Аннотировать общее использование ярлыков

  • @type {typeName}
    • *означает любой тип
    • ?значит может бытьnull
    • !указать, что это не может бытьnull
    • []представляет массив
/**
* @type {number}
*/
var foo1;

/**
* @type {*}
* @desc 任何类型
*/
var foo2;

/**
* @type {?string}
* @desc string或者null
*/
var foo3;

  • @param {} name - some description
    • Необязательные параметры должны быть добавлены к имени параметра[]
    • Если параметр имеет значение по умолчанию, его необходимо использовать=выражать
    • Если параметр Object, вы можете продолжать использовать@paramдетализировать его свойства
    • по нескольким параметрам...выражать
/**
 * @func
 * @desc 一个带参数的函数
 * @param {string} a - 参数a
 * @param {number} b=1 - 参数b默认值为1
 * @param {string} c=1 - 参数c有两种支持的取值  1—表示x  2—表示xx
 * @param {object} d - 参数d为一个对象
 * @param {string} d.e - 参数d的e属性
 * @param {object[]} g - 参数g为一个对象数组
 * @param {string} g.h - 参数g数组中一项的h属性
 * @param {string} [j] - 参数j是一个可选参数
 */
 function foo(a, b, c, d, g, j) {}

/**
 * @func
 * @desc 一个带若干参数的函数
 * @param {...string} a - 参数a
 */
function bar(a) {}

Узнать больше можно посмотретьJSDoc

Расширение

Условные комментарии IE (IE5+)

Условные комментарии IE делятся на следующие ситуации:

  • Разрешить только IE интерпретировать и выполнять<!--[if IE]><![endif]-->
  • Разрешить только выполнение интерпретации конкретной версии IE<!--[if IE 7]><![endif]-->
  • Разрешить только версии, отличные от IE, выполнять комментарии<!--[if !IE 7]><![endif]-->
  • Разрешить выполнение комментариев только выше или ниже определенной версии IE<!--[if gt IE 7]><![endif]-->
 <head>
  	<title>IE 条件注释</title>
  
  	<!-- 是 IE 时 -->
    <!--[if IE]> 
        <link href="style.css" rel="stylesheet" type="text/css" />
    <![endif]-->
  
    <!-- 是 IE 7 时 -->
 	 	<!--[if IE 7]>
       <link href="style.css" rel="stylesheet" type="text/css" />
    <![endif]-->
 
    <!-- 不是 IE 7 时 -->
  	<!--[if !IE 7]>
        <link href="style.css" rel="stylesheet" type="text/css" />
    <![endif]-->
  
  	<!-- 大于 IE 7 时 -->
  	<!--[if gt IE 7]>
       <link href="style.css" rel="stylesheet" type="text/css" />
    <![endif]-->
 
  	<!-- 小于 IE 7 时 -->
   	<!--[if lt IE 7]>
       <link href="style.css" rel="stylesheet" type="text/css" />
    <![endif]-->
</head>

# (знак фунта) комментарий и ''' (тройная кавычка) комментарий

  • #Обычно появляются в различных файлах конфигурации скриптов, использовании и однострочных комментариях JS.//в основном то же самое. Также часто используется в Python
  • '''представляет собой синтаксис многострочного комментария в Python, использующий два'''содержит прокомментированные абзацы
# python 的单行注释一
	print("I could have code like this.") # python 的单行注释二

# print("This won't run.") # 被注释的代码

'''
	被三引号包裹的段落
	可以随意折行
	也可以注释代码
	print("This won't run.")
'''

Аннотация "исполнена"?

Как мы все знаем, закомментированный код не будет выполнен. Но редактор увидел более интересный фрагмент кода при поиске информации, строка комментария в Java "выполняется"?

public class Test {
	public static void main(String[] args) {
		String name = "赵大";
		// \u000dname="钱二";
		System.out.println(name);
	}
}

Результат выполнения этого кода钱二, то есть в этом коде вступает в силу «закомментированная» строка кода!

Проблема с этим кодом\u000dв этой строке специальных символов.\u000dпредставляет собой строку символов Unicode, представляющую новую строку. Компилятор Java не только компилирует код, но и анализирует символы Юникода. В приведенном выше коде поместите\u000dПосле синтаксического анализа следующий код переходит на следующую строку, которая выходит за рамки комментария (диапазон комментария однострочного комментария находится только на текущей строке), поэтому результат выполнения такой:钱二вместо赵大. (следующее)

public class Test {
	public static void main(String[] args) {
		String name = "赵大";
		//
		name="钱二";
		System.out.println(name);
	}
}

По сути, когда код выполняетсяname="钱二"Не прокомментировано, но обернуто (добавлены странные знания). Так что помните, комментарии действительно не исполняются!

Плагины, связанные с аннотациями

Здесь я рекомендую несколько плагинов Vscode, связанных с аннотациями, которые, как мне кажется, просты в использовании, их можно найти по адресуsetting.jsonПользовательские настройки в файле (вы можете открыть файл Vscode через «Файл - Настройки - Настройки»settings.json)

  • koroFileHeaderПлагин для генерации комментариев к заголовкам файлов и комментариев к функциям в vscode.
  • Добавить комментарии к заголовку файла
    • Добавьте комментарий в начале файла, чтобы записать информацию о файле/параметры/выходные данные файла и т. д.
    • Поддерживайте пользователей в настройке параметров аннотаций для адаптации к различным потребностям и аннотациям.
    • При сохранении файла автоматически обновлять время последнего редактирования и редактор
    • горячая клавиша:window:ctrl+alt+i,mac:ctrl+cmd+i,linux:ctrl+meta+i

  • Добавить комментарий к функции рядом с курсором
    • Автоматически генерировать шаблон аннотации при наведении курсора
    • Поддерживает настраиваемые пользователем параметры аннотаций
    • горячая клавиша:window:ctrl+alt+t,mac:ctrl+cmd+t,linux:ctrl+meta+t
    • Клавиша быстрого доступа недоступна, скорее всего она занята,обратитесь сюда
    • Настраиваемые параметры по умолчанию

  • Better CommentsУлучшайте комментарии к коду, добавляя к ним предупреждения, информацию, задачи и т. д. Используя это расширение, вы сможете классифицировать аннотации на:
    • Новостная рассылка
    • Запрос
    • Сделать
    • Подчеркивать
    • Закомментированный код также можно стилизовать так, чтобы кода там не было.
    • Настраивается для указания других желаемых стилей аннотаций

  • TODO HighlightВыделите TODO, FIXME и любые ключевые слова
    • Выделите встроенные ключевые слова, переопределяя внешний вид с помощью пользовательских настроек.
    • Вы также можете настроить ключевые слова

говорить с фактами

Слова говорят без доказательств, видишь, значит веришь. Давайте посмотрим на конкретную ситуацию в реальной разработке:

  • нет аннотаций
const noWarehousetemIds = beSelectSkucontainer.reduce((arr, itemId) => {
    const res = Object.keys(selectRowskey[itemId]).every((skuId) => {
      const sku = selectRowskey[itemId][skuId];
      return !!sku.warehouseCode || lodashGet(warehouses, '[0].code');
    });
    if (!res) {
      arr.push(itemId);
    }
    return arr;
  }, []);
  if (noWarehousetemIds.length > 0 || noStockItemIds.length > 0) {
    const itemIds = Array.from(new Set([...noWarehousetemIds, ...noStockItemIds]));
    const itemNames = itemIds.map(i => this.itemNameMap[i].itemName);
    return Modal.warning({
      title: '错误提示',
      content: `“${itemNames.join(',')}”库存信息未完善,请完善库存信息`,
    });
  }
  • Общие замечания
// 遍历当前所有选中的sku,查找出没有库存的itemId
const noStockItemIds = beSelectSkucontainer.reduce((arr, itemId) => {
  const res = Object.keys(selectRowskey[itemId]).every((skuId) => {
    const sku = selectRowskey[itemId][skuId];
    return !!sku.stockQuantity;
  });
  if (!res) {
    arr.push(itemId);
  }
  return arr;
}, []);
// 有一条sku的库存为空时进入校验
if (noStockItemIds.length > 0) {
  const itemNames = itemIds.map(i => this.itemNameMap[i].itemName);
  return Modal.warning({
    title: '错误提示',
    content: `“${itemNames.join(',')}”库存信息未完善,请完善库存信息`,
  });
}
  • лучшая аннотация
// 遍历当前所有选中的sku,查找出没有库存的itemId
const noStockItemIds = beSelectSkucontainer.reduce((arr, itemId) => {
    // selectRowskey是一个对象,以itemId为key,sku对象作为value,sku对象以skuId作为key,sku作为value,只有selectRowskey下所有itemId下的sku都有库存才算校验通过
    /*
        数据格式:
        selectRowskey: {
          12345678: { // itemId
              123456: { // skuId
              name: 'sku',
              }
          }
        }
      */
    const res = Object.keys(selectRowskey[itemId]).every((skuId) => {
        const sku = selectRowskey[itemId][skuId];
        return !!sku.stockQuantity;
    });
    // 只要有一条sku没有库存时,就塞到arr中,返回给noStockItemIds数组
    if (!res) {
        arr.push(itemId);
    }
    return arr;
}, []);
// 有一条sku的库存为空时进入校验
if (noStockItemIds.length > 0) {
    // 根据id查找商品名称
    const itemNames = itemIds.map(i => this.itemNameMap[i].itemName);
    Modal.warning({
        title: '错误提示',
        content: `“${itemNames.join(',')}”库存信息未完善,请完善库存信息`,
    });
}

Увидев приведенный выше код, вы можете четко понять важность наличия комментариев и ясность комментариев. Если вы пишете заметку, но все еще не можете ее понять, лучше ее не писать.

Поэтому мало просто писать комментарии, нужно описать функцию определенного куска кода и указать логику, чтобы разработчики могли «безмозгло» листать.

Я видел, как кто-то ранее публиковал такую ​​картинку в рабочей группе (как показано ниже), что лично я считаю хорошим примером комментариев к коду:

Эпилог

Увидев это, вы уже имеете собственное понимание важности аннотаций. Есть еще несколько моментов, о которых следует помнить при написании комментариев:

  • Комментарии должны быть краткими и четкими. Комментариев достаточно, чтобы кратко описать функции или реализовать логику, не добавляя комментариев к каждой строке кода.

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

    Если у вас есть какие-либо комментарии, пожалуйста, оставьте сообщение в области комментариев ниже ~

использованная литература

Зачем писать заметки Спецификации и примеры комментариев к коду js/javascript Специальные комментарии в коде — роль TODO, FIXME, XXX Роль комментариев и как их писать Вы уверены, что аннотации Java не будут выполняться? 80% людей не знают.Подробное объяснение условных комментариев браузера IE Вопросы об условных комментариях IE в CSS

Рекомендуемое чтение

Мой фронтальный путь карьерного роста

Говоря о XSS-атаках в React

Карьера

ZooTeam, молодая, увлеченная и творческая команда, связанная с отделом исследований и разработок продукции Zhengcaiyun, базируется в живописном Ханчжоу. В настоящее время в команде более 40 фронтенд-партнеров, средний возраст которых составляет 27 лет, и почти 30% из них — инженеры полного стека, настоящая молодежная штурмовая группа. В состав членов входят «ветераны» солдат из Ali и NetEase, а также первокурсники из Чжэцзянского университета, Университета науки и технологий Китая, Университета Хандянь и других школ. В дополнение к ежедневным деловым связям, команда также проводит технические исследования и фактические боевые действия в области системы материалов, инженерной платформы, строительной платформы, производительности, облачных приложений, анализа и визуализации данных, а также продвигает и внедряет ряд внутренних технологий. Откройте для себя новые горизонты передовых технологических систем.

Если вы хотите измениться, вас забросали вещами, и вы надеетесь начать их бросать; если вы хотите измениться, вам сказали, что вам нужно больше идей, но вы не можете сломать игру; если вы хотите изменить , у вас есть возможность добиться этого результата, но вы не нужны; если вы хотите изменить то, чего хотите достичь, вам нужна команда для поддержки, но вам некуда вести людей; если вы хотите изменить установившийся ритм, это будет "5 лет рабочего времени и 3 года опыта работы"; если вы хотите изменить исходный Понимание хорошее, но всегда есть размытие того слоя оконной бумаги.. , Если вы верите в силу веры, верьте, что обычные люди могут достичь необыкновенных вещей, и верьте, что они могут встретить лучшего себя. Если вы хотите участвовать в процессе становления бизнеса и лично способствовать росту фронтенд-команды с глубоким пониманием бизнеса, надежной технической системой, технологиями, создающими ценность, и побочным влиянием, я думаю, что мы должны говорить. В любое время, ожидая, пока вы что-нибудь напишете, отправьте это наZooTeam@cai-inc.com