Всем привет, я Чжан Сансуй🤣, фронтенд правовой системы⚖️. Люблю делиться🖋️, люблю Bingbing🧊🧊.
Приветствую вас, друзья, чтобы добавить меня в WeChat: maomaoibingbing, пригласите вас в группу, обсудите вместе и с нетерпением жду возможности расти вместе со всеми🥂.
предисловие
Комментарий считается знакомым моим друзьям, но именно этот небольшой комментарий многие друзья любят и ненавидят так же, как и проектный документ. Я не люблю писать комментарии и ненавижу, когда другие не пишут комментарии. Здесь мы обсудимJavaScriptа такжеCSSЯ надеюсь, что с помощью этой статьи вы вернете свою любовь к аннотациям и получите удовольствие от кодирования, как море звезд.
1. Грамматика
1. CSS-комментарии
/* css 注释 */
2. Комментарии JavaScript
// 单行注释
/**
* 多行注释，注意第一行最好用两个 *
* ...
*/
/*
当然，除了两端的 * 必须加以外，其他的 * 不加也行
...
*/
2. Основное использование
1. Однострочные комментарии
При нормальных обстоятельствах прямо над кодом появляется однострочный комментарий, который служит напоминанием:
/* 用注释备注 CSS 类名的功能 */
/* 顶部组件 */
.hd {
position: fixed;
width: 100vw;
}
/* 版心 */
.container {
margin: 16px auto;
width: 1200px;
}
// 用单行注释备注简单的信息
const userName = ""; // 用户名
const userAvatar = ""; // 用户头像
// xxx函数
const myFunction = () => {};
2. Многострочные комментарии
Многострочные комментарии обычно используются, когда нужно отметить слишком много информации, и часто появляются вJavaScriptвозле функции. Прежде всего возникает вопрос: зачем использовать многострочные комментарии вместо однострочных? Давайте посмотрим на следующий код:
// xxx函数
const myFunction = ({ id, name, avatar, list, type }) => {
// 此处省略 30 行代码
};
Друзья, возможно, видели, что функция, которая передает пять параметров и несколько строк кода внутри, имеет только короткую строку комментариев.Может быть, вы можете вспомнить назначение этой функции и тип параметров, и нужно ли ее передавать или нет, когда вы Но если через какое-то время вы вернетесь к предыдущему коду, короткие комментарии могут стать для вас проблемой.Не говоря уже о том, что комментариев нет, прикольно не писать комментарии, а оглядываться на крематорий кода.Цель написания комментариев — улучшить читаемость кода. Напротив, следующие комментарии гораздо яснее:
/**
* 调整滚动距离
* 用于显示给定 id 元素
* @param id string 必传 元素 id
* @param distance number 非必传 距离视口最顶部距离(避免被顶部固定定位元素遮挡)
* @returns null
*/
export const scrollToShowElement = (id = "", distance = 0) => {
return () => {
if (!id) {
return;
};
const element = document.getElementById(id);
if (!element) {
return;
};
const top = element?.offsetTop || 0;
window.scroll(0, top - distance);
};
};
Для сложных функций следует добавлять многострочные комментарии в унифицированном формате к объявлению функции, а также однострочные комментарии к внутренней сложной логике и важным переменным, которые взаимодействуют и дополняют друг друга. Формат многострочных комментариев для объявлений функций обычно следующий:
/**
* 函数名称
* 函数简介
* @param 参数1 参数1数据类型 是否必传 参数1描述
* @param 参数2 参数2数据类型 是否必传 参数2描述
* @param ...
* @returns 返回值
*/
Преимущество многострочных комментариев в том, что они четкие и понятные, а недостаток в том, что они более громоздки (можно сгенерировать шаблоны комментариев к функциям JavaScript с помощью редактора). Рекомендуется, чтобы логически простые функции использовали однострочные комментарии, а логически сложные функции и общедоступные/служебные функции использовали многострочные комментарии.
Конечно, хорошее имя переменной/функции также может снизить затраты на размышления читателя и может перейти к моей статье:«Элегантное нейминг».
3. Расширенное использование
Будь тоcssещеJavaScriptСтановится все больше и больше проблем, время, когда все больше и больше кода, но и заставляет код искать изменения. Итак, нам нужно разобрать код по модулям, и с комментарием вверху каждого модуля с помощью пустой строки, разделенной в конце.
/* 以下代码仅为示例 */
/* 模块1 */
/* 类名1 */
.class-a {}
/* 类名2 */
.class-b {}
/* 类名3 */
.class-c {}
/* 模块2 */
/* 类名4 */
.class-d {}
/* 类名5 */
.class-e {}
/* ... */
// 以下代码仅为示例
// 模块1
// 变量1
const value1 = "";
// 变量2
const value2 = "";
// 变量3
const value3 = "";
// 函数1
const myFunction1 = () => {};
// 模块2
// 变量4
const value4 = "";
// 变量5
const value5 = "";
// 变量6
const value6 = "";
// 函数2
const myFunction2 = () => {};
// ...
Эффект там, но, похоже, не очевидно, поэтому мы добавляем в комментарии-или=Попробуем разделить:
/* ------------------------ 模块1 ------------------------ */
/* 类名1 */
.class-a {}
/* 类名2 */
.class-b {}
/* 类名3 */
.class-c {}
/* ------------------------ 模块2 ------------------------ */
/* 类名4 */
.class-d {}
/* 类名5 */
.class-e {}
/* ... */
// 以下代码仅为示例
/* ======================== 模块1 ======================== */
// 变量1
const value1 = "";
// 变量2
const value2 = "";
// 变量3
const value3 = "";
// 函数1
const myFunction1 = () => {};
/* ======================== 模块2 ======================== */
// 变量4
const value4 = "";
// 变量5
const value5 = "";
// 变量6
const value6 = "";
// 函数2
const myFunction2 = () => {};
// ...
Интуитивно видно, что эффект сегментации аннотаций расширенной версии лучше, а дискриминация выше. Качественный код часто требует самых незатейливых комментариев для сегментации. вJavaScriptКомментарий «разделенная строка» рекомендует использовать многострочный комментарий.
«Великолепные» разделительные линии:
/* ------------------------ 华丽的分割线 ------------------------ */
/* ======================== 华丽的分割线 ======================== */
4. Расширение
Если рабочий хочет хорошо работать, он должен сначала заточить свои инструменты. Ниже я хотел бы порекомендовать несколькоVSCodeПлагин редактора комментариев.
1. Better Comments
Введение в плагин: Вы можете изменить цвет аннотаций, есть четыре выделенных цвета (по умолчанию красный, оранжевый, зеленый, синий) и черный с зачеркиванием. Цвета можно изменить в настройках плагина. На картинке ниже показан цвет экземпляра и мое использование в проекте, а комментарий соответствует ситуации.
Обязательный плагин для программистов, которым нравятся навороты, он может эффективно улучшить разрешение и эстетику аннотаций и с этого момента полюбить аннотации. Нужно всего лишь добавить один или несколько символов, чтобы изменить цвет комментария прямо из коробки.
// ! 红色的高亮注释,双斜线后加英文叹号 ! 配置
// todo 橙色的高亮注释,双斜线后加 todo 函数
// * 绿色的高亮注释,双斜线后加 * 变量
// ? 蓝色的高亮注释,双斜线后加英文问号 ? 组件
// // 黑色带删除线的注释,双斜线后加双斜线 // 说明
2. koroFileHeader
Знакомство с подключаемым модулем: добавляйте комментарии к заголовку файла, добавляйте комментарии к функциям курсора и добавляйте шаблоны комментариев, такие как Будда никогда не благословляет ошибки, божественные звери и т. д. одним щелчком мыши.
3. JavaScript Comment Snippet
Введение в плагин: он может быстро генерировать комментарии JavaScript, которые не популярны, но просты в использовании.
резюме
Я должен сказать, что комментарии действительно важны в процессе написания кода, чтобы писать более элегантный и удобный код, мы также должны записывать самую важную информацию в комментарии. проектаREADME.markdownи аннотации в проекте похожи на проектруководствоТочно так же непроектные разработчики могут быстрее прочитать смысл кода и идею кодирования. Пусть код добьется нас, пусть код изменит мир, пусть комментарии сопровождают меня!