当前位置: 首页 > 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 | ------------------------ 开启和关闭事件调度器…...

Linux应用开发之网络套接字编程(实例篇)

服务端与客户端单连接 服务端代码 #include <sys/socket.h> #include <sys/types.h> #include <netinet/in.h> #include <stdio.h> #include <stdlib.h> #include <string.h> #include <arpa/inet.h> #include <pthread.h> …...

Java 语言特性(面试系列2)

一、SQL 基础 1. 复杂查询 &#xff08;1&#xff09;连接查询&#xff08;JOIN&#xff09; 内连接&#xff08;INNER JOIN&#xff09;&#xff1a;返回两表匹配的记录。 SELECT e.name, d.dept_name FROM employees e INNER JOIN departments d ON e.dept_id d.dept_id; 左…...

【人工智能】神经网络的优化器optimizer(二):Adagrad自适应学习率优化器

一.自适应梯度算法Adagrad概述 Adagrad&#xff08;Adaptive Gradient Algorithm&#xff09;是一种自适应学习率的优化算法&#xff0c;由Duchi等人在2011年提出。其核心思想是针对不同参数自动调整学习率&#xff0c;适合处理稀疏数据和不同参数梯度差异较大的场景。Adagrad通…...

shell脚本--常见案例

1、自动备份文件或目录 2、批量重命名文件 3、查找并删除指定名称的文件&#xff1a; 4、批量删除文件 5、查找并替换文件内容 6、批量创建文件 7、创建文件夹并移动文件 8、在文件夹中查找文件...

【C语言练习】080. 使用C语言实现简单的数据库操作

080. 使用C语言实现简单的数据库操作 080. 使用C语言实现简单的数据库操作使用原生APIODBC接口第三方库ORM框架文件模拟1. 安装SQLite2. 示例代码:使用SQLite创建数据库、表和插入数据3. 编译和运行4. 示例运行输出:5. 注意事项6. 总结080. 使用C语言实现简单的数据库操作 在…...

AI书签管理工具开发全记录(十九):嵌入资源处理

1.前言 &#x1f4dd; 在上一篇文章中&#xff0c;我们完成了书签的导入导出功能。本篇文章我们研究如何处理嵌入资源&#xff0c;方便后续将资源打包到一个可执行文件中。 2.embed介绍 &#x1f3af; Go 1.16 引入了革命性的 embed 包&#xff0c;彻底改变了静态资源管理的…...

企业如何增强终端安全?

在数字化转型加速的今天&#xff0c;企业的业务运行越来越依赖于终端设备。从员工的笔记本电脑、智能手机&#xff0c;到工厂里的物联网设备、智能传感器&#xff0c;这些终端构成了企业与外部世界连接的 “神经末梢”。然而&#xff0c;随着远程办公的常态化和设备接入的爆炸式…...

代理篇12|深入理解 Vite中的Proxy接口代理配置

在前端开发中,常常会遇到 跨域请求接口 的情况。为了解决这个问题,Vite 和 Webpack 都提供了 proxy 代理功能,用于将本地开发请求转发到后端服务器。 什么是代理(proxy)? 代理是在开发过程中,前端项目通过开发服务器,将指定的请求“转发”到真实的后端服务器,从而绕…...

安宝特方案丨船舶智造的“AR+AI+作业标准化管理解决方案”(装配)

船舶制造装配管理现状&#xff1a;装配工作依赖人工经验&#xff0c;装配工人凭借长期实践积累的操作技巧完成零部件组装。企业通常制定了装配作业指导书&#xff0c;但在实际执行中&#xff0c;工人对指导书的理解和遵循程度参差不齐。 船舶装配过程中的挑战与需求 挑战 (1…...

DingDing机器人群消息推送

文章目录 1 新建机器人2 API文档说明3 代码编写 1 新建机器人 点击群设置 下滑到群管理的机器人&#xff0c;点击进入 添加机器人 选择自定义Webhook服务 点击添加 设置安全设置&#xff0c;详见说明文档 成功后&#xff0c;记录Webhook 2 API文档说明 点击设置说明 查看自…...