Loading [MathJax]/jax/output/CommonHTML/config.js
前往小程序,Get更优阅读体验!
立即前往
首页
学习
活动
专区
圈层
工具
发布
首页
学习
活动
专区
圈层
工具
MCP广场
社区首页 >专栏 >代码中的注释应该遵循哪些规范和原则?

代码中的注释应该遵循哪些规范和原则?

作者头像
程序员阿伟
发布于 2024-12-09 07:47:32
发布于 2024-12-09 07:47:32
1880
举报

代码中的注释应该遵循以下规范和原则:

  1. 注释应该清晰明确:注释应该用清晰的语言描述代码的功能、逻辑和目的,以便其他开发者能够轻松理解。
  2. 注释应该是准确的:注释内容应该与代码一致,不应该产生歧义或误导。
  3. 注释应该是简洁的:注释应该尽量简短,避免使用冗长的语句或过多的详细描述。
  4. 注释应该是有用的:注释应该提供有关代码的关键信息,如参数和返回值的说明、重要变量的解释等。
  5. 注释应该是及时更新的:当代码发生变化时,注释应该及时更新以反映最新的信息。
  6. 注释应该是规范的:注释应该遵循团队所采用的代码注释规范,以保持代码的一致性和可读性。
  7. 注释应该避免显而易见的内容:不需要注释每一行代码,特别是那些很容易理解的代码。
  8. 注释应该解释代码的意图而不是实现细节:注释应该解释为什么要写这段代码,而不是如何实现它。
  9. 注释应该避免写过多的历史记录:代码版本控制系统应该用于记录和追踪代码的历史变化,而不是将它们写入注释中。
  10. 注释应该避免写不必要的注释:对于易于理解和自解释的代码,不需要过多的注释。
本文参与 腾讯云自媒体同步曝光计划,分享自作者个人站点/博客。
原始发表:2024-05-30,如有侵权请联系 cloudcommunity@tencent.com 删除

本文分享自 作者个人站点/博客 前往查看

如有侵权,请联系 cloudcommunity@tencent.com 删除。

本文参与 腾讯云自媒体同步曝光计划  ,欢迎热爱写作的你一起参与!

评论
登录后参与评论
暂无评论
推荐阅读
编辑精选文章
换一批
代码整洁之道-读书笔记之注释
当发现你的代码需要写注释的时候,一定要多思考一下,有没有办法通过代码表达,能不能把注释写的尽量的少
特特
2022/10/26
4000
​2019 DevOps 必备面试题——代码版本控制篇
这可能是你在面试中遇到的最简单的问题。我的建议是首先给出版本控制的定义:它是一个记录文件变化的系统,以便你以后可以调用特定版本的文件。版本控制系统由一个中央共享存储库组成,队友可以在其中提交文件的更改,接下来你可以提到版本控制的用途。版本控制允许你:
腾讯云 CODING
2019/09/02
2.2K0
​2019 DevOps 必备面试题——代码版本控制篇
别死写代码,这25条比涨工资都重要
如果每个程序开发人员都只是周而复始地写代码,想必编程的工作就会让很多程序员发狂。那么如何在枯燥的工作中寻找乐趣,我认为我们要对工作保持激情和兴奋感、始终学习的态度,还需要掌握一些实用高效的编程技巧,这样对于提升工作乐趣和效率大有裨益。今天小编就跟大家分享一下25个实用编程小技巧,希望可以给开发编程人员的工作和学习带来更多的思考。
JAVA葵花宝典
2019/05/24
3300
程序员应该避免的5种代码注释
程序员应该避免的5种代码注释 你有没有这样的经历:别人审查过你的代码之后给出的注释,你认为是没有必要的?注释代码是为了提高代码的可读性,目的是为了能让其他人更容易理解你的代码。 我特别讨厌这5种注释类型以及制造它们的程序员。希望你不是其中之一。 1.自以为很了不得的程序员 public class Program { static void Main(string[] args) { string message = "Hello World!"; // 07/24/201
用户1289394
2018/02/27
6510
程序员应该避免的5种代码注释
1.1 起步 - 关于版本控制
本章关于开始学习 Git。 我们从介绍有关版本控制工具的一些背景知识开始,然后讲解如何在你的系统运行 Git,最后是关于如何设置 Git 开始你的工作。 通过本章的学习,你应该了解为什么 Git 这么流行,为什么你应该使用 Git 以及你应该如何设置以便使用 Git。
shaonbean
2019/05/26
5140
代码规范(如何提升代码质量)
# 好的例子:命名清晰 def calculate_area(width, height): return width * height ​ # 坏的例子:命名不清晰 def calc(w, h): return w * h
奥耶可乐冰
2024/05/30
7020
Git 提交竟然还能这么用?
之前已经给大家分享过 Git / GitHub 的学习指南,感兴趣的同学可以先看视频了解:https://www.bilibili.com/video/BV1KZ4y1e7cG。
程序员鱼皮
2023/10/28
2970
Git 提交竟然还能这么用?
测开必备|Git操作
版本控制是一种记录一个或若干文件内容变化,以便将来查阅特定版本修订情况的系统。 在本书所展示的例子中,我们对保存着软件源代码的文件作版本控制,但实际上,你可以对任何类型的文件进行版本控制。
互联网金融打杂
2022/08/01
3170
测开必备|Git操作
代码注释对于程序员重要吗?
程序员对代码注释可以说是又爱又恨又双标……你是怎么看待程序员不写注释这一事件的呢?
此星光明
2024/02/02
2430
Python零基础从入门到精通详细教程1-注释
关于Python的介绍、安装以及开发工具的安装宏哥这里就不做赘述了,需要了解的可以自行查找资料或者看宏哥之前的文章进行了解和学习。这里宏哥就直接上干货,开门见山。今天我们首先来讲解和学习一下Python的注释,大家不要觉得简单而不重视或者忽略了它。注释在我们日常工作中还是非常重要的。否则我们就会出现以下几种窘境:
北京-宏哥
2024/01/26
5980
Python零基础从入门到精通详细教程1-注释
Git提交规范
Git是目前最流行的分布式版本控制系统,它能够帮助开发者高效管理项目代码。在进行Git操作时,我们需要对代码进行提交,以记录下每一次修改的内容。而Git提交规范则是指在代码提交时,根据一定的格式要求进行提交信息的书写,并在注释中尽可能详细地记录修改的内容,以方便其他人查看。
疯狂的KK
2023/04/03
9870
程序员应该避免的 5 种代码注释
你有没有这样的经历:别人审查过你的代码之后给出的注释,你认为是没有必要的?注释代码是为了提高代码的可读性,目的是为了能让其他人更容易理解你的代码。 我特别讨厌这5种注释类型以及制造它们的程序员。希望你
用户2017109
2018/06/19
5280
写不好代码注释?这份注释指南一定要收好
这也是不少程序员一直头疼的问题,比如接手新代码时,没有注释,完全搞不清逻辑;自己写的注释,跟不上代码修改,成了误导;复杂逻辑不知道咋注释,别人也看不懂。
敏捷开发
2024/07/29
5440
写不好代码注释?这份注释指南一定要收好
hhdb客户端介绍(38)
在项目的开发和维护中,定期进行代码注释的审查工作是确保代码质量的关键步骤。以下是一些具体的步骤和方法,用于确保注释的准确性和有用性,并及时修正或删除过时或错误的注释:
恒辉信达
2024/12/21
690
git笔记,一篇文章从入门到精通
git 会了clone,pull,push,建分支,合并,暂存,commit,,rollback,merge就可以了,配合idea软件使用,就超级棒了
一写代码就开心
2022/05/09
2550
git笔记,一篇文章从入门到精通
工作必备Git保姆级教学
    版本控制是一种记录一个或若干文件内容变化,以便将来查阅特定版本修订情况的系统。     在公司中,一般以团队的形式进行项目的开发。在一个团队中,每一个团队成员都需要一份相同的代码,而大家又都基于这份代码去开发着不同的功能,过程中就会产生相当多的问题,针对这些问题,我们可以采用版本控制的方式来解决,也因此诞生了很多的版本控制工具,如市面上比较常见的 cvs/svn/git 等等。
上分如喝水
2021/08/16
3250
工作必备Git保姆级教学
2021github仓库操作流程手册指南「建议收藏」
​ 集中化的版本控制系统诸如 CVS,svn 以及 Perforce 等,都有一个单一的集 中管理的服务器,保存所有文件的修订版本,而协同工作的人们都通过客户端连到 这台服务器,取出最新的文件或者提交更新。多年以来,这已成为版本控制系统的 标准做法
全栈程序员站长
2022/09/13
4950
Git详解——Git概述原理及安装细节
Git是一个免费的、开源的分布式版本控制系统 ,可以快速高效地处理从小型到大型的各种项目 。Git易于学习,占地面积小,性能极快 。 它具有廉价的本地库 ,方便的暂存区域和多个工作流分支等特性。
timerring
2022/07/20
3090
Git详解——Git概述原理及安装细节
Git最全系列教程(一)
本章介绍开始使用 Git 前的相关知识。我们会先了解一些版本控制工具的历史背景,然后试着让 Git 在你的系统上跑起来,直到最后配置好,可以正常开始开发工作。读完本章,你就会明白为什么 Git 会如此流行,为什么你应该立即开始使用它。
兔云小新LM
2019/07/24
7190
Git最全系列教程(一)
Git Commit Message 最佳实践
Git 是一个免费开源的分布式版本控制系统,由 Linux 之父 Linus Torvalds 于 2005 年开发,最初的目的用于管理 Linux 内核的开发。
恋喵大鲤鱼
2023/10/12
8720
Git Commit Message 最佳实践
相关推荐
代码整洁之道-读书笔记之注释
更多 >
领券
问题归档专栏文章快讯文章归档关键词归档开发者手册归档开发者手册 Section 归档