当前位置: 首页 > news >正文

如何在前端项目中制定代码注释规范

本文是前端代码规范系列文章,将涵盖前端领域各方面规范整理,其他完整文章可前往主页查阅~

开始之前,介绍一下​最近很火的开源技术,低代码。

作为一种软件开发技术逐渐进入了人们的视角里,它利用自身独特的优势占领市场一角——让使用者可以通过可视化的方式,以更少的编码,更快速地构建和交付应用软件,极大程度地降低了软件的开发、配置、部署和培训成本。

应用地址: https://www.jnpfsoft.com
开发语言:Java/.net

这是一个基于 Java Boot/.Net Core 构建的简单、跨平台快速开发框架。前后端封装了上千个常用类,方便扩展;采用微服务、前后端分离架构,集成了代码生成器,支持前后端业务代码生成,满足快速开发;框架集成了表单、报表、图表、大屏等各种常用的 Demo 方便直接使用;后端框架支持 Vue2、Vue3,平台即可私有化部署,也支持 K8S 部署。

代码注释是软件开发中的重要组成部分,它帮助开发者理解代码的功能和目的,同时也是代码维护和团队协作的基础。一个清晰的注释规范能够提高代码的可读性和维护性。本文将介绍如何在前端项目中制定代码注释规范。

1. 注释的类型

在前端项目中,我们通常有两种类型的注释:

  • 单行注释:用于简短的描述或解释单个语句。
  • 多行注释:用于描述复杂逻辑或文件、模块的信息。

2. 单行注释

单行注释应该紧跟在代码的上一行或同一行的末尾。注释内容与代码或上一行注释应保持至少一个空格的距离。

// 正确的单行注释
const count = 1; // 初始化计数器// 错误的单行注释
const count = 1;//初始化计数器

3. 多行注释

多行注释通常用于文件头部,描述整个文件的功能,或者用于复杂逻辑的解释。多行注释应该有一个清晰的开始和结束,内容与星号之间保持一个空格。

/*** 正确的多行注释* 这是一个用于计算数组总和的函数* @param {number[]} numbers - 要计算的数字数组* @return {number} 数组的总和*/
function sum(numbers) {// ...
}/* 错误的多行注释
这是一个用于计算数组总和的函数
@param {number[]} numbers - 要计算的数字数组
@return {number} 数组的总和
*/
function sum(numbers) {// ...
}

4. JSDoc注释

JSDoc是一种流行的注释规范,它不仅可以提高代码的可读性,还可以被一些工具用来生成文档。在前端项目中,推荐使用JSDoc来注释函数、类和方法。

/*** 计算数组总和* @param {number[]} numbers - 要计算的数字数组* @returns {number} 数组的总和*/
function sum(numbers) {return numbers.reduce((acc, current) => acc + current, 0);
}

5. 注释的内容

注释应该清晰、简洁、有目的。避免无意义的注释或过度注释。注释应该解释为什么这么做,而不是什么在做。代码本身应该清晰到足以表达它在做什么。

// 正确的注释
// 因为用户可能会输入负数,所以在加法前进行检查
if (number < 0) {throw new Error('Number must be positive');
}// 错误的注释
// 检查数字是否小于0
if (number < 0) {throw new Error('Number must be positive');
}

6. 代码修改时更新注释

当代码发生变化时,相关的注释也应该相应地更新。过时的注释会误导其他开发者,降低代码的可读性。

7. 注释模板

对于一些重复性的注释内容,如组件、模块、函数等,可以制定统一的注释模板。

/*** 组件名称* * 描述这个组件的作用和功能* * @prop {PropType} propName - 对prop的描述*/

8. 工具支持

可以使用一些工具来强制执行注释规范,如ESLint的注释相关规则,或者使用Prettier来自动格式化注释,这块会在后续的系列文章中单独说明。

9. 避免注释整块代码

不应该在代码库中保留被注释掉的代码。这些代码往往是过时的,并且会给其他开发者带来困惑。如果需要保留代码的历史版本,应该使用版本控制系统git来管理。

// 错误:注释掉的代码
// function oldCalculate() {
//   // ...
// }

10. 特殊注释标记

在代码中使用特殊的注释标记(如TODO, FIXME, NOTE)来标识需要特别注意的地方,这些标记可以帮助开发者快速定位到需要进一步工作的部分。

  • TODO: 表示代码中将来需要添加或完成的功能。通常用于提醒开发者还有功能未实现或需要进一步的工作。
  • FIXME: 指出代码中存在问题,需要修复。这通常表示代码能够运行,但结果可能不是预期的,或者代码本身可能不稳定。
  • HACK: 指代码中的临时解决方案或者不够优雅的代码。这通常用于快速修复问题,但长远来看可能需要更好的解决方案。
  • NOTE: 用于强调代码中的某个特别重要的信息,比如解释某个复杂算法的逻辑或者提醒为什么要以特定方式实现代码。
  • OPTIMIZE: 提示代码的性能可以进一步优化。这不一定表示代码有问题,但可能存在提高效率的机会。
  • REVIEW: 表示代码需要额外的审查,以确定是否满足需求或是否存在更好的实现方式。
  • DEPRECATED: 表明代码已经过时,不应该被使用或将来会被移除。
  • NOCOMMIT: 这是一个警告,表示代码不应该被提交到版本控制系统中。这常用于开发过程中的临时改动,如调试代码。
// TODO: 增加异常处理
function loadData() {// ...
}// FIXME: 这里的算法实现有问题,以后需要优化
function calculate() {// ...
}// NOTE: 这是一个临时解决方法
function temporaryFunction() {// ...
}

使用这些注释标签可以帮助团队成员快速识别代码中的特定部分,但它们也不应该过度使用。过多的TODO或FIXME可能表明代码质量问题,应该定期审查和解决这些标记。

11. 开发工具注释

开发工具基本都有便捷指令支持注释,本文只列举在 VSCode 和 WebStorm 这两个编辑器中对代码注释的便捷方式或插件。

在 VSCode 中添加代码注释:

  • 手动添加:通过快捷键 Ctrl + /(Windows/Linux)或 Cmd + /(Mac)添加行注释,在选中代码后按下快捷键即可。也可以手动编写注释。
  • 插件:VSCode 有很多代码注释相关的插件,如 Document This、jsdoc-comment、better-comments、vscode-todo-highlight 等,可以通过 VSCode 的扩展市场安装并使用,提供更丰富的注释功能。

在 WebStorm 中添加代码注释:

  • 自动添加:在函数或方法上方输入 /** 并按下 Enter 键,WebStorm 将会自动生成函数注释的模板,然后你只需填写相应的信息即可。
  • 自定义模板:可以在 WebStorm 的设置中自定义注释模板,满足团队的特定需求或遵循特定的注释规范。

无论是在 VSCode 还是 WebStorm 中,都可以通过简单的快捷键操作或安装插件来实现代码注释,使代码更易读、易维护。

总结

良好的注释规范有助于提高代码质量,促进团队协作,加快新成员的项目熟悉速度,不仅能帮助自己和他人快速理解代码,还能提高代码的可维护性。在前端项目中,注释不仅仅是给自己看的,更是给团队中其他成员看的,因此应当保持注释的清晰、准确和及时更新。

通过本文介绍的注释规范,希望能帮助你在前端项目中写出更清晰、更规范的注释。

相关文章:

如何在前端项目中制定代码注释规范

本文是前端代码规范系列文章&#xff0c;将涵盖前端领域各方面规范整理&#xff0c;其他完整文章可前往主页查阅~ 开始之前&#xff0c;介绍一下​最近很火的开源技术&#xff0c;低代码。 作为一种软件开发技术逐渐进入了人们的视角里&#xff0c;它利用自身独特的优势占领市…...

一位苹果手机硬件工程师繁忙的一天

早晨&#xff1a;迎接新的一天 7:00 AM - 起床 早晨七点准时起床。洗漱、吃早餐后&#xff0c;查看手机上的邮件和消息&#xff0c;以便提前了解今天的工作安排和优先事项。 7:30 AM - 前往公司 开车前往位于加州库比蒂诺的苹果总部。在车上习惯性地听一些与电子工程相关的播…...

Python | 使用均值编码(MeanEncoding)处理分类特征

在特征工程中&#xff0c;将分类特征转换为数字特征的任务称为编码。 有多种方法来处理分类特征&#xff0c;如OneHotEncoding和LabelEncoding&#xff0c;FrequencyEncoding或通过其计数替换分类特征。同样&#xff0c;我们可以使用均值编码(MeanEncoding)。 均值编码 均值…...

面试-java异常体系

1.java异常体系 error类是指与jvm相关的问题。如系统崩溃&#xff0c;虚拟机错误&#xff0c;内存空间不足。 非runtime异常不处理&#xff0c;程序就没有办法执行。 一旦遇到异常抛出&#xff0c;后面的异常就不会进行。 (1)常见的error以及exception 2.java异常要点分析…...

Clickhouse 的性能优化实践总结

文章目录 前言性能优化的原则数据结构优化内存优化磁盘优化网络优化CPU优化查询优化数据迁移优化 前言 ClickHouse是一个性能很强的OLAP数据库&#xff0c;性能强是建立在专业运维之上的&#xff0c;需要专业运维人员依据不同的业务需求对ClickHouse进行有针对性的优化。同一批…...

变工况下转子、轴承数据采集及测试

1.固定工况下的数据采集 1.wireshark抓包 通过使用 Wireshark 抓包和 Linux 端口重放技术&#xff0c;可以模拟实际机械设备的运行环境&#xff0c;从而减少实地验证软件和算法的复杂性和麻烦。 打开设备正常运转&#xff0c;当采集器通过网口将数据发送到电脑时&#xff0c…...

泰迪智能科技与成都文理学院人工智能与大数据学院开展校企合作交流

近日&#xff0c;在推动高等教育与产业深度融合的背景下&#xff0c;成都文理学院人工智能与大数据学院携手广东泰迪智能科技股份有限公司开展“专业建设交流会”。人工智能与大数据学院院长胡念青、院长助理陈坚、骨干教师刘超超、孙沛、赵杰、文运、胡斌、邹杰出席本次交流会…...

ubuntu22.04安装初始化

目录 1. 概述2. 修改参数3. 修改限制4. 修改源6. 虚拟机关闭swap分区7. 配置系统信息7.1 设置主机名7.2 设置时区7.3 安装常用工具包7.4 设置时间同步7.5 关闭 selinux 1. 概述 CentOS 7 马上就停止支持服务了&#xff0c;未雨绸缪&#xff0c;整理Ubuntu 22.04的 初始化脚本。…...

学习新语言方法总结(一)

随着工作时间越长&#xff0c;单一语言越来越难找工作了&#xff0c;需要不停地学习新语言来适应&#xff0c;总结一下自己学习新语言的方法&#xff0c;这次以GO为例&#xff0c;原来主语言是PHP &#xff0c;自学GO 了解语言特性&#xff0c;知道他是干嘛的 go语言&#xff0…...

Mysql数据的备份与恢复

一.备份概述 备份的主要目的是灾难恢复&#xff0c;备份还可以测试应用、回滚数据修改、查询历史数据、审计等。 1.数据备份的重要性 在企业中数据的价值至关重要&#xff0c;数据保障了企业业务的正常运行。因此&#xff0c;数据的安全性及数据的可靠性是运维的重中之重&…...

规上!西安市支持培育商贸企业达限纳统应统尽统申报奖励补助要求政策

西安市支持培育商贸企业达限纳统应统尽统工作方案 为加快培育消费市场主体&#xff0c;支持商贸企业扩大经营、做大做强&#xff0c;指导企业达限纳统、应统尽统&#xff0c;不断扩大我市限额以上商贸企业数量规模&#xff0c;促进全市经济社会高质量发展&#xff0c;结合我市…...

Go语言测试第二弹——基准测试

在前一篇文章中&#xff0c;我们讲解了Go语言中最基础的单元测试&#xff0c;还没有看过的可以自行去查看&#xff0c;这篇文章我们详细了解Go语言里面的基准测试。 基准测试 基准测试&#xff0c;也就是BenchmarkTest&#xff0c;基准测试是用来测试代码性能的的一种方法&…...

关于“刘亦菲为什么无人敢娶”的问题❗❗❗

关于“刘亦菲为什么无人敢娶”的问题&#xff0c; 实际上涉及到多个方面的因素&#xff0c; 以下是对这些因素的详细分析&#xff1a;1.事业心重&#xff1a;刘亦菲作为华语影视圈的知名女星&#xff0c;她的演艺事业非常成功&#xff0c; 这也意味着她将大量的时间和精力投…...

LeetCode:经典题之141、142 题解及延伸

系列目录 88.合并两个有序数组 52.螺旋数组 567.字符串的排列 643.子数组最大平均数 150.逆波兰表达式 61.旋转链表 160.相交链表 83.删除排序链表中的重复元素 389.找不同 1491.去掉最低工资和最高工资后的工资平均值 896.单调序列 206.反转链表 92.反转链表II 141.环形链表 …...

rk3568 OpenHarmony 串口uart与电脑通讯开发案例

一、需求描述&#xff1a; rk3568开发板运行OpenHarmony4.0&#xff0c;通过开发板上的uart串口与电脑进行通讯&#xff0c;相互收发字符串。 二、案例展示 1、开发环境&#xff1a; &#xff08;1&#xff09;rk3568开发板 &#xff08;2&#xff09;系统&#xff1a;OpenHar…...

canvas画布旋转问题

先说一下为什么要旋转的目的&#xff1a;因为在画布上签名&#xff0c;在不同的设备上我需要不同方向的签名图片&#xff0c;电脑是横屏&#xff0c;手机就是竖屏&#xff0c;所以需要把手机的签名旋转270&#xff0c;因此写了这个方法。 关于画布旋转的重点就是获取到你的画布…...

vue3 【提效】自动导入框架方法 unplugin-auto-import 实用教程

是否还在为每次都需要导入框架方法而烦恼呢&#xff1f; // 每次都需手动导入框架方法 import { ref } from vuelet num ref(0)用 unplugin-auto-import 来帮你吧&#xff0c;以后只需这样写就行啦&#xff01; let num ref(0)官方示例如下图 使用流程 1. 安装 unplugin-au…...

clip系列改进Lseg、 group ViT、ViLD、Glip

Lseg 在clip后面加一个分割head&#xff0c;然后用分割数据集有监督训练。textencoder使用clip&#xff0c;frozen住。 group ViT 与Lseg不同&#xff0c;借鉴了clip做了真正的无监督学习。 具体的通过group block来做的。使用学习的N个group token&#xff08;可以理解为聚类…...

Ubuntu下TensorRT与trtexec工具的安装

新版&#xff08;这里测试的是10.1版&#xff09;的onnx转tensorrt engine工具trtexec已经集成在TensorRT中&#xff0c;不需要额外单独安装。 教程来源于此网页&#xff1a;https://medium.com/moshiur.faisal01/install-tensorrt-with-command-line-wrapper-trtexec-on-unun…...

MySQL定时任务

事件调度器操作 查看事件调度器是否开启&#xff1a;ON 表示已开启。 show variables like %event_scheduler%; ------------------------ | Variable_name | Value | ------------------------ | event_scheduler | ON | ------------------------ 开启和关闭事件调度器…...

uniapp 对接腾讯云IM群组成员管理(增删改查)

UniApp 实战&#xff1a;腾讯云IM群组成员管理&#xff08;增删改查&#xff09; 一、前言 在社交类App开发中&#xff0c;群组成员管理是核心功能之一。本文将基于UniApp框架&#xff0c;结合腾讯云IM SDK&#xff0c;详细讲解如何实现群组成员的增删改查全流程。 权限校验…...

conda相比python好处

Conda 作为 Python 的环境和包管理工具&#xff0c;相比原生 Python 生态&#xff08;如 pip 虚拟环境&#xff09;有许多独特优势&#xff0c;尤其在多项目管理、依赖处理和跨平台兼容性等方面表现更优。以下是 Conda 的核心好处&#xff1a; 一、一站式环境管理&#xff1a…...

SciencePlots——绘制论文中的图片

文章目录 安装一、风格二、1 资源 安装 # 安装最新版 pip install githttps://github.com/garrettj403/SciencePlots.git# 安装稳定版 pip install SciencePlots一、风格 简单好用的深度学习论文绘图专用工具包–Science Plot 二、 1 资源 论文绘图神器来了&#xff1a;一行…...

服务器硬防的应用场景都有哪些?

服务器硬防是指一种通过硬件设备层面的安全措施来防御服务器系统受到网络攻击的方式&#xff0c;避免服务器受到各种恶意攻击和网络威胁&#xff0c;那么&#xff0c;服务器硬防通常都会应用在哪些场景当中呢&#xff1f; 硬防服务器中一般会配备入侵检测系统和预防系统&#x…...

微信小程序云开发平台MySQL的连接方式

注&#xff1a;微信小程序云开发平台指的是腾讯云开发 先给结论&#xff1a;微信小程序云开发平台的MySQL&#xff0c;无法通过获取数据库连接信息的方式进行连接&#xff0c;连接只能通过云开发的SDK连接&#xff0c;具体要参考官方文档&#xff1a; 为什么&#xff1f; 因为…...

pikachu靶场通关笔记22-1 SQL注入05-1-insert注入(报错法)

目录 一、SQL注入 二、insert注入 三、报错型注入 四、updatexml函数 五、源码审计 六、insert渗透实战 1、渗透准备 2、获取数据库名database 3、获取表名table 4、获取列名column 5、获取字段 本系列为通过《pikachu靶场通关笔记》的SQL注入关卡(共10关&#xff0…...

Reasoning over Uncertain Text by Generative Large Language Models

https://ojs.aaai.org/index.php/AAAI/article/view/34674/36829https://ojs.aaai.org/index.php/AAAI/article/view/34674/36829 1. 概述 文本中的不确定性在许多语境中传达,从日常对话到特定领域的文档(例如医学文档)(Heritage 2013;Landmark、Gulbrandsen 和 Svenevei…...

技术栈RabbitMq的介绍和使用

目录 1. 什么是消息队列&#xff1f;2. 消息队列的优点3. RabbitMQ 消息队列概述4. RabbitMQ 安装5. Exchange 四种类型5.1 direct 精准匹配5.2 fanout 广播5.3 topic 正则匹配 6. RabbitMQ 队列模式6.1 简单队列模式6.2 工作队列模式6.3 发布/订阅模式6.4 路由模式6.5 主题模式…...

视觉slam十四讲实践部分记录——ch2、ch3

ch2 一、使用g++编译.cpp为可执行文件并运行(P30) g++ helloSLAM.cpp ./a.out运行 二、使用cmake编译 mkdir build cd build cmake .. makeCMakeCache.txt 文件仍然指向旧的目录。这表明在源代码目录中可能还存在旧的 CMakeCache.txt 文件,或者在构建过程中仍然引用了旧的路…...

A2A JS SDK 完整教程:快速入门指南

目录 什么是 A2A JS SDK?A2A JS 安装与设置A2A JS 核心概念创建你的第一个 A2A JS 代理A2A JS 服务端开发A2A JS 客户端使用A2A JS 高级特性A2A JS 最佳实践A2A JS 故障排除 什么是 A2A JS SDK? A2A JS SDK 是一个专为 JavaScript/TypeScript 开发者设计的强大库&#xff…...