10个代码注释及格式化的最佳实践

作者：qapo | 来源：互联网 | 2023-05-17 07:31

代码注释及格式化关乎代码的可读性，而代码可读性对于代码可维护性又是至关重要的，因此一些编程的小细节有助于提高代码可维护性。本文列举了一些代码注释及格式化的优秀示例。一、注释注释是代码的一部分，其重

代码注释及格式化关乎代码的可读性，而代码可读性对于代码可维护性又是至关重要的，因此一些编程的小细节有助于提高代码可维护性。本文列举了一些代码注释及格式化的优秀示例。

一、注释

注释是代码的一部分，其重要性显而易见。缺少注释的代码可以说是没有用的，虽然有人建议使用自文档化代码，不过我们认为自文档化+代码文档是最好的。

1. 只在必要时使用注释

也就是说不需要对每一行都使用注释
Java代码

int count = 0; // 将count的初始值赋为0(?!?)

但缺少注释会增加维护难度，所以变量、方法的命名应该易于理解
Java代码

int s = sqrt(v1) + v2 / v3 + fread(s). getChar(0) //(?!?)
List<int> getVal(int val, int len, String op) //(?!?)

2. 错误的注释还不如没有注释，应尽量避免。

3. 为重要的且没有自文档化的变量写注释。

4. 为公开的方法写注释（例如JavaDoc declaration），当然，这些注释应该是真的有必要添加的。

5. 类似“了解”、“待办”的注释也许对当天来说很重要，但之后应该删除。

二、格式化

有很多开发工具（如maven checkstyle）都提供代码格式化的功能，且格式化操作可在代码保存时自动进行，但这些格式不一定符合公司的格式规则，因此在使用之前要对其进行设置。

1. 使用一致的括号格式。括号一般都加在当前行的尾部或新一行的首部，选择一种添加方式，并在所有代码行中保持相同的格式。

2. 使用一致的空行。空行用于分隔代码和语义组，提高代码可读性。例如使用3行空行来表示方法的结束，没有空行或每行代码间都加空行却不利于代码美观。

3. 留意首行缩进。正确的缩进对于语义块来说就像括号和空行一样重要。

4. 限制每行的字符数，提高可读性。大多数程序员认可的限制数为80个左右。

5. 使用一致的空格，通常以下的这些情况要使用空格：

Java代码

//运算符和变量之间
a += b , c = 0; (a == b)
//语句关键字和括号之间
if (value) {, public class A {
//循环的“；”号后
for (int i = 0; i < length; i++)
//类型和变量之间
(int) value , (String) value

推荐阅读

java
Java实现大数乘法（分治算法）

本文介绍了使用Java实现大数乘法的分治算法，包括输入数据的处理、普通大数乘法的结果和Karatsuba大数乘法的结果。通过改变long类型可以适应不同范围的大数乘法计算。 ... [详细]

蜡笔小新 2023-12-14 15:43:50
ip
开发笔记:加密&json&StringIO模块&BytesIO模块

篇首语：本文由编程笔记#小编为大家整理，主要介绍了加密&json&StringIO模块&BytesIO模块相关的知识，希望对你有一定的参考价值。一、加密加密 ... [详细]

蜡笔小新 2023-12-14 15:18:35
io
Java太阳系小游戏分析和源码详解

本文介绍了一个基于Java的太阳系小游戏的分析和源码详解。通过对面向对象的知识的学习和实践，作者实现了太阳系各行星绕太阳转的效果。文章详细介绍了游戏的设计思路和源码结构，包括工具类、常量、图片加载、面板等。通过这个小游戏的制作，读者可以巩固和应用所学的知识，如类的继承、方法的重载与重写、多态和封装等。 ... [详细]

蜡笔小新 2023-12-14 19:53:34
match
lua语言闭包、模式匹配、日期、编译、模块的特性及应用

本文介绍了lua语言中闭包的特性及其在模式匹配、日期处理、编译和模块化等方面的应用。lua中的闭包是严格遵循词法定界的第一类值，函数可以作为变量自由传递，也可以作为参数传递给其他函数。这些特性使得lua语言具有极大的灵活性，为程序开发带来了便利。 ... [详细]

蜡笔小新 2023-12-14 18:18:21
io
在类中定义数组时出错 - Error on defining arrays in class

Iamtryingtomakeaclassthatwillreadatextfileofnamesintoanarray,thenreturnthatarra ... [详细]

蜡笔小新 2023-12-14 17:38:12
ip
C#学习教程：在Console中工作但在Windows窗体中不工作的异步代码分享

本文分享了一个关于在C#中使用异步代码的问题，作者在控制台中运行时代码正常工作，但在Windows窗体中却无法正常工作。作者尝试搜索局域网上的主机，但在窗体中计数器没有减少。文章提供了相关的代码和解决思路。 ... [详细]

蜡笔小新 2023-12-14 15:56:00
io
Java猜拳小游戏代码

本文介绍了一个Java猜拳小游戏的代码，通过使用Scanner类获取用户输入的拳的数字，并随机生成计算机的拳，然后判断胜负。该游戏可以选择剪刀、石头、布三种拳，通过比较两者的拳来决定胜负。 ... [详细]

蜡笔小新 2023-12-14 15:39:08
io
Java序列化对象传给PHP的方法及原理解析

本文介绍了Java序列化对象传给PHP的方法及原理，包括Java对象传递的方式、序列化的方式、PHP中的序列化用法介绍、Java是否能反序列化PHP的数据、Java序列化的原理以及解决Java序列化中的问题。同时还解释了序列化的概念和作用，以及代码执行序列化所需要的权限。最后指出，序列化会将对象实例的所有字段都进行序列化，使得数据能够被表示为实例的序列化数据，但只有能够解释该格式的代码才能够确定数据的内容。 ... [详细]

蜡笔小新 2023-12-14 15:25:15
io
Java容器中的compareto方法排序原理解析

本文从源码解析Java容器中的compareto方法的排序原理，讲解了在使用数组存储数据时的限制以及存储效率的问题。同时提到了Redis的五大数据结构和list、set等知识点，回忆了作者大学时代的Java学习经历。文章以作者做的思维导图作为目录，展示了整个讲解过程。 ... [详细]

蜡笔小新 2023-12-14 13:53:31
java
求解hdu 1003 java题目的动态规划优化方法

本文讨论了如何优化解决hdu 1003 java题目的动态规划方法，通过分析加法规则和最大和的性质，提出了一种优化的思路。具体方法是，当从1加到n为负时，即sum(1,n)sum(n,s)，可以继续加法计算。同时，还考虑了两种特殊情况：都是负数的情况和有0的情况。最后，通过使用Scanner类来获取输入数据。 ... [详细]

蜡笔小新 2023-12-14 13:11:00
header
如何自行分析定位SAP BSP错误

The“BSPtag”Imentionedintheblogtitlemeansforexamplethetagchtmlb:configCelleratorbelowwhichi ... [详细]

蜡笔小新 2023-12-14 19:58:05
select
SQL日志收缩及截断方法详解

本文详细介绍了SQL日志收缩的方法，包括截断日志和删除不需要的旧日志记录。通过备份日志和使用DBCC SHRINKFILE命令可以实现日志的收缩。同时，还介绍了截断日志的原理和注意事项，包括不能截断事务日志的活动部分和MinLSN的确定方法。通过本文的方法，可以有效减小逻辑日志的大小，提高数据库的性能。 ... [详细]

蜡笔小新 2023-12-14 18:23:25
schema
如何使用Java获取服务器硬件信息和磁盘负载率

本文介绍了使用Java编程语言获取服务器硬件信息和磁盘负载率的方法。首先在远程服务器上搭建一个支持服务端语言的HTTP服务，并获取服务器的磁盘信息，并将结果输出。然后在本地使用JS编写一个AJAX脚本，远程请求服务端的程序，得到结果并展示给用户。其中还介绍了如何提取硬盘序列号的方法。 ... [详细]

蜡笔小新 2023-12-14 13:56:20
io
LeetCode笔记：剑指Offer 41. 数据流中的中位数（Java、堆、优先队列、知识点）

本文介绍了LeetCode剑指Offer 41题的解题思路和代码实现，主要涉及了Java中的优先队列和堆排序的知识点。优先队列是Queue接口的实现，可以对其中的元素进行排序，采用小顶堆的方式进行排序。本文还介绍了Java中queue的offer、poll、add、remove、element、peek等方法的区别和用法。 ... [详细]

蜡笔小新 2023-12-14 13:34:58
java
树莓派Linux基础（一）：查看文件系统的命令行操作

本文介绍了在树莓派上通过SSH服务使用命令行查看文件系统的操作，包括cd命令用于变更目录、pwd命令用于显示当前目录位置、ls命令用于显示文件和目录列表。详细讲解了这些命令的使用方法和注意事项。 ... [详细]

蜡笔小新 2023-12-14 13:33:39

qapo

这个家伙很懒，什么也没留下！

Tags | 热门标签

RankList | 热门文章