从细节出发:提高你的代码可读性

简介: 在编程的世界中,我们总是不断追求更高的性能,更优雅的设计,以及更复杂的特性。然而,我们不应忽视一个基本且重要的原则——代码的可读性。那么究竟何谓代码的可读性?顾名思义,代码可读性是指代码可理解的程度,是代码作者通过代码这个媒介,将需要表达的信息输出到读者脑中的能力。所以有的人说好的代码必然有清晰完整的注释,也有人说代码即注释,是代码简洁之道的最高境界,后者的观点飞哥持保留意见,毕竟真正能够做到代码即注释的有几人呢?

在编程的世界中,我们总是不断追求更高的性能,更优雅的设计,以及更复杂的特性。然而,我们不应忽视一个基本且重要的原则——代码的可读性。那么究竟何谓代码的可读性?顾名思义,代码可读性是指代码可理解的程度,是代码作者通过代码这个媒介,将需要表达的信息输出到读者脑中的能力。所以有的人说好的代码必然有清晰完整的注释,也有人说代码即注释,是代码简洁之道的最高境界,后者的观点飞哥持保留意见,毕竟真正能够做到代码即注释的有几人呢?

我们先看个例子:

public StepExitEnum doExecute(StepContext stepContext) throws Exception {
    String targetFilePath = this.getOriginFilePath(stepContext.getJobContext());//获取目标路径
    File targetDir = new File(targetFilePath);
    if (!targetDir.exists()) {
        targetDir.mkdirs();//如果不存在目录则创建
    }

    String encryptedFilePath = this.getEncryptedFilePath(stepContext.getJobContext());//获取加密文件路径
    String fileName = this.getFileName(stepContext);//获取文件名
    File[] encryptedFiles = new File(encryptedFilePath).listFiles(this.buildFilenameFilter(fileName));//过滤文件

    FileEncryptor dencryptor = this.buildFileEncryptor(stepContext);//创建FileEncryptor
    Stream.of(encryptedFiles)
            .forEach(encryptFile -> {
                File targetFile = new File(targetFilePath, encryptFile.getName());
                dencryptor.invoke(encryptFile, targetFile);//解密文件
            });

    return StepExitEnum.CONTINUING;
}

这种代码很常见,耐着性子其实也容易看懂:创建目录->读取加密文件->解密文件,就当前来说其实满足了业务需求也就可以了,但不够优雅;从长期来讲,这会产生bad smell,首先,“如果不存在目录则创建”、“获取文件名”这类注释有何意义?有可能这是coder当时的方案思路,但是否真的需要?它确确实实会影响看到这段代码的程序员的注意力了,但往往却并没有让程序员获取到任何有价值信息;其次,若想要理解doExecute这个方法的目的,必须通读代码,而开发人员也许只是想知道它做了什么事;最后,这个方法如果某一行出问题了,那么影响范围是整个业务流程。如果后期需要改动,大部分人可能会增加条件判断,或是在后面继续追加代码实现,最后会导致越来越难以阅读,这其实也就是“能运行就不要动它”这个梗的根源了,因为没人能读明白它到底做了什么,但又不得不改。

那究竟如何才能提高代码的可读性?毕竟代码可读性作为团队协作开发的前提,是软件可维护性的前提,是代码评审的前提,也是代码评审中的核心关注点之一。

1、 抽象,合理的业务逻辑抽象
“一个方法只应该做一件事”,这依赖coder对业务逻辑、对功能实现的深入理解和合理抽象,这才能清晰的区分出各个功能的边界,或者说是如何定义这件“事”。
合理的抽象,从功能角色、职责划分上就很清晰,有了这个基础,才能清晰的编写业务逻辑代码,而不是堆砌各种条件判断和循环,同时带着两条斜杠和注释,这是可读性的基础。
2、 各司其职,职责单一
一个方法只做一件事,扩展到一个类也如此,职责单一,归根结底还得基于合理的抽象,所以,它其实是抽象的一种具体体现,二者总是相辅相成。
3、 使用清晰、简洁的命名:
变量和函数的命名是代码可读性的关键。命名应该简洁且具有描述性,能够清晰地表达其用途。避免使用模糊或者过于简化的命名。
4、 保持适当的注释:
注释是提高代码可读性的重要手段。对于复杂的逻辑和算法,适当的注释能够帮助读者理解代码的目的和工作原理。同时,注释也应该保持简洁和清晰,避免过多的解释。
5、 遵循编码规范:
各种编程语言都有一套推荐的编码规范,如Python的PEP8,Java的Google Java Style Guide等。这些规范不仅有助于保持代码的一致性,也有助于提高代码的可读性。
6、 使用有意义的空格和格式化:
在代码中使用适当的空格和格式化可以帮助读者更好地理解代码的结构和逻辑。例如,使用空格来分隔变量和函数名,使用空行来分隔不同的代码块等。
7、 限制代码行长度:
过长的代码行往往难以阅读和理解。一般来说,限制代码行的长度可以有助于提高代码的可读性。大多数的IDE和编辑器都提供了代码行限制的功能。

基于以上建议,我们再来看看以下代码:

// 类名:RegexValidator
// 函数名:validateString
// 函数功能:正则验证字符串
// POM依赖包:无

import java.util.regex.Pattern;

public class RegexValidator {
    /**
     * 正则验证字符串
     * @param regex 正则表达式
     * @param str 待验证的字符串
     * @return 是否匹配正则表达式
     */
    public static boolean validateString(String regex, String str) {
        if (regex == null || str == null) { // 检查入参是否为空
            throw new IllegalArgumentException("Regex and string cannot be null"); // 抛出异常,正则表达式和字符串不能为空
        }

        Pattern pattern = Pattern.compile(regex); // 编译正则表达式
        return pattern.matcher(str).matches(); // 使用正则表达式匹配字符串,并返回结果
    }
}

// 函数示例
// 正则验证字符串示例
// 入参:regex,正则表达式;str,待验证的字符串
// 出参:isValid,是否匹配正则表达式
// 调用示例:
// String regex = "\\d+";
// String str = "12345";
// boolean isValid = RegexValidator.validateString(regex, str);
// System.out.println(isValid);
// 输出结果:例如,通过正则表达式"\\d+"验证字符串"12345",结果为:true
// 则输出结果为:true

通过分析,不难发现:
1、命名:类名RegexValidator,函数名validateString都清晰明了,可以让人一眼看出它们的用途。
2、注释:在validateString函数上方,有一段详细的注释,解释了函数的功能、参数和返回值。这可以帮助读者理解代码的功能。
3、异常处理:在函数内部,对输入参数进行了空值检查,并抛出了IllegalArgumentException异常,这使得读者能够清楚地知道如果输入为空值会发生什么。
4、示例调用和输出:在代码的最后部分,提供了一个示例调用和输出结果的注释,这使得读者能够更容易地理解如何使用这个函数,以及它的预期输出是什么。
5、代码规范性:代码的格式很规范,缩进、空格等都符合Java的编码规范,这有助于提高代码的可读性。

综上,这是一个可读性非常好,很易于理解和使用的代码。而这段代码则是有全栈式全自动件开发工具soflu软件机器人推出的FuncGPT(慧函数)生成。作为飞算SoFlu软件机器人的一个重要组成部分,FuncGPT(慧函数)支持所有类型函数创建。通过自然语言描述Java函数需求,实时生成高质量、高可读性的Java函数代码。生成代码可直接复制到IDEA,或一键导入Java全自动开发工具函数库。想体验秒级生成可读性高的代码,现在免费下载使用FuncGPT(慧函数)[https://a.d4t.cn/QKKmTr]。

相关文章
|
设计模式 算法 Java
设计模式第十五讲:重构 - 改善既有代码的设计(下)
设计模式第十五讲:重构 - 改善既有代码的设计
294 0
|
17天前
|
项目管理
为什么清晰的思路能提升效率?
面对任务繁多、思路混乱的情况,结构化思维能有效帮助我们理清头绪。通过将复杂问题拆解为“目标—资源—流程—反馈”等模块,结合像板.栗.看.板.这样的工具,以卡片形式清晰呈现每一步骤,不仅使工作井井有条,还能显著提升效率。让文档成为你的“第二大脑”,助力职场发展。
|
6月前
|
算法 安全 编译器
【简洁的代码永远不会掩盖设计者的意图】如何写出规范整洁的代码
【简洁的代码永远不会掩盖设计者的意图】如何写出规范整洁的代码
60 1
|
C语言
C数组超细节精髓
C数组超细节精髓
85 0
|
Java 编译器 应用服务中间件
代码开发优化细节
带有final修饰符的类是不可派生的。在Java核心API中,有许多应用final的例子,例如java.lang.String,整个类都是final的。为类指定final修饰符可以让类不可以被继承,为方法指定final修饰符可以让方法不可以被重写。如果指定了一个类为final,则该类所有的方法都是final的。Java编译器会寻找机会内联所有的final方法,内联对于提升Java运行效率作用重大,具体参见Java运行期优化。此举能够使性能平均提高50% 。
212 2
代码开发优化细节
|
设计模式 Java Apache
设计模式第九讲:常见重构技巧 - 去除不必要的!=
设计模式第九讲:常见重构技巧 - 去除不必要的!=
|
设计模式 Java 测试技术
设计模式第十五讲:重构 - 改善既有代码的设计(上)
设计模式第十五讲:重构 - 改善既有代码的设计
336 0
|
人工智能 自然语言处理 Java
提高代码可读性的秘诀:注释的重要性
A:你写代码怎么连注释都不加? B:老大为什么要加注释? A:你不加注释,你怎么知道我能看懂你的代码? B:遇到问题你找到就可以了啊? A:那你哪天生病了请假了闹情绪了离职了,公司怎么办? B:我现在反正没觉得有什么问题,我对公司也很满意,安心啦! 又是00后整顿职场的一段精彩演绎。不可置否,在实际的软件开发过程中,确实有很多开发人员依然不愿意写注释认为这会浪费时间,或者自认为他们的代码足够清晰,不需要额外的解释。但这种想法too young too simple,代码注释对于项目的质量和效率有着深远的影响,在软件开发中的重要性不容小觑。
项目实战典型案例14——代码结构混乱 逻辑边界不清晰 页面美观设计不足
项目实战典型案例14——代码结构混乱 逻辑边界不清晰 页面美观设计不足
125 0
|
前端开发
案例14-代码结构逻辑混乱,页面设计不美观
代码结构逻辑混乱,页面设计不美观