提高代码可读性的秘诀:注释的重要性

举报
努力的阿飞 发表于 2023/10/13 11:19:47 2023/10/13
【摘要】 A:你写代码怎么连注释都不加?B:老大为什么要加注释?A:你不加注释,你怎么知道我能看懂你的代码?B:遇到问题你找到就可以了啊?A:那你哪天生病了请假了闹情绪了离职了,公司怎么办?B:我现在反正没觉得有什么问题,我对公司也很满意,安心啦! 又是00后整顿职场的一段精彩演绎。不可置否,在实际的软件开发过程中,确实有很多开发人员依然不愿意写注释认为这会浪费时间,或者自认为他们的代码足够清晰,不需...

A:你写代码怎么连注释都不加?

B:老大为什么要加注释?

A:你不加注释,你怎么知道我能看懂你的代码?

B:遇到问题你找到就可以了啊?

A:那你哪天生病了请假了闹情绪了离职了,公司怎么办?

B:我现在反正没觉得有什么问题,我对公司也很满意,安心啦!

 

又是00后整顿职场的一段精彩演绎。不可置否,在实际的软件开发过程中,确实有很多开发人员依然不愿意写注释认为这会浪费时间,或者自认为他们的代码足够清晰,不需要额外的解释。但这种想法too young too simple,代码注释对于项目的质量和效率有着深远的影响,在软件开发中的重要性不容小觑。

  • 提高代码可读性

良好的注释可以帮助其他开发人员更好地理解代码的逻辑和功能。当你或其他人需要阅读代码时,可以通过阅读注释来快速理解代码的作用和目的。这有助于提高代码的可读性和可维护性。

  • 代码文档化

注释可以作为代码的文档,提供关于代码的详细信息,包括函数的作用、参数的用途以及函数的返回值等。这些信息对于其他开发人员和自己在未来回顾代码时非常有用,可以避免重新阅读和理解代码的时间和精力。

  • 代码质量和错误排查

适当的注释可以帮助发现代码中的问题,如逻辑错误、拼写错误等。当其他开发人员或自己在阅读代码时,如果发现与注释不一致的代码行为或逻辑,就可以及时进行修正,从而提高代码质量。

  1. 提高开发效率

编写注释的时间实际上是投资。虽然编写注释似乎会减缓开发速度,但实际上,通过注释,可以节省大量时间。通过快速理解代码的功能和逻辑,可以更快地开展工作,提高开发效率。

  1. 团队合作和知识共享

在团队开发中,注释是知识共享的重要工具。团队成员可以通过阅读注释来了解其他成员的工作思路和实现方法。这有助于团队成员之间的沟通和协作,提高团队合作的效率。

充分认识到注释的重要性,但是迫于交付时间的压力,以及部分开发人员的能力边界问题,如何编写清晰、有用的注释,无从下手。而随着AI技术的发展,很多代码辅助工具在一定程度上很好的解决了这个问题。

以智能开发工具飞算SoFlu软件机器人推出的函数AI生成器—FuncGPT(慧函数)为例,作为飞算SoFlu软件机器人的一个重要组成部分,FuncGPT(慧函数)支持所有类型函数创建。通过自然语言描述Java函数需求,实时生成高质量、高可读性的Java函数代码。包含清晰的代码注释,帮助开发工程师理解函数的用途和输入输出。生成代码可直接复制到IDEA,或一键导入Java全自动开发工具函数库。

以通过FuncGPT(慧函数)生成的”BigDecimal的表达式运算”为例:

// 类名:BigDecimalCalculator
// 函数名:calculateExpression
// 函数功能:使用BigDecimal计算表达式的结果
// POM依赖包:
// <dependency>
//     <groupId>org.apache.commons</groupId>
//     <artifactId>commons-lang3</artifactId>
//     <version>3.12.0</version>
// </dependency>

import org.apache.commons.lang3.StringUtils;

import java.math.BigDecimal;
import java.math.RoundingMode;
import java.util.Stack;

public class BigDecimalCalculator {
    /**
     * 使用BigDecimal计算表达式的结果
     * @param expression 要计算的表达式
     * @return 计算结果
     */
    public static BigDecimal calculateExpression(String expression) {
        if (StringUtils.isBlank(expression)) {
            throw new IllegalArgumentException("Expression cannot be blank");
        }

        Stack<BigDecimal> numberStack = new Stack<>();
        Stack<Character> operatorStack = new Stack<>();

        for (int i = 0; i < expression.length(); i++) {
            char ch = expression.charAt(i);
            if (Character.isDigit(ch)) {
                StringBuilder sb = new StringBuilder();
                while (i < expression.length() && (Character.isDigit(expression.charAt(i)) || expression.charAt(i) == '.')) {
                    sb.append(expression.charAt(i));
                    i++;
                }
                i--;

                BigDecimal number = new BigDecimal(sb.toString());
                numberStack.push(number);
            } else if (ch == '(') {
                operatorStack.push(ch);
            } else if (ch == ')') {
                while (!operatorStack.isEmpty() && operatorStack.peek() != '(') {
                    BigDecimal result = performOperation(numberStack, operatorStack);
                    numberStack.push(result);
                }
                if (!operatorStack.isEmpty() && operatorStack.peek() == '(') {
                    operatorStack.pop();
                }
            } else if (isOperator(ch)) {
                while (!operatorStack.isEmpty() && hasHigherPrecedence(ch, operatorStack.peek())) {
                    BigDecimal result = performOperation(numberStack, operatorStack);
                    numberStack.push(result);
                }
                operatorStack.push(ch);
            }
        }

        while (!operatorStack.isEmpty()) {
            BigDecimal result = performOperation(numberStack, operatorStack);
            numberStack.push(result);
        }

        return numberStack.pop();
    }

    private static boolean isOperator(char ch) {
        return ch == '+' || ch == '-' || ch == '*' || ch == '/';
    }

    private static boolean hasHigherPrecedence(char op1, char op2) {
        if ((op1 == '*' || op1 == '/') && (op2 == '+' || op2 == '-')) {
            return true;
        }
        return false;
    }

    private static BigDecimal performOperation(Stack<BigDecimal> numberStack, Stack<Character> operatorStack) {
        BigDecimal num2 = numberStack.pop();
        BigDecimal num1 = numberStack.pop();
        char operator = operatorStack.pop();

        BigDecimal result;
        switch (operator) {
            case '+':
                result = num1.add(num2);
                break;
            case '-':
                result = num1.subtract(num2);
                break;
            case '*':
                result = num1.multiply(num2);
                break;
            case '/':
                result = num1.divide(num2, 2, RoundingMode.HALF_UP);
                break;
            default:
                throw new IllegalArgumentException("Invalid operator");
        }

        return result;
    }
}

// 函数示例
// 使用BigDecimal计算表达式的结果示例
// 入参:expression,要计算的表达式
// 出参:result,计算结果
// 调用示例:
// String expression = "2.5 + 3 * (4 - 1)";
// BigDecimal result = BigDecimalCalculator.calculateExpression(expression);
// System.out.println(result);
// 输出结果:例如,计算表达式"2.5 + 3 * (4 - 1)"的结果为:11.5
// 则输出结果为:11.5

FuncGPT(慧函数)生成的这段函数使用了合理的命名和注释,函数和变量的命名清晰明了,注释对函数的功能和参数进行了说明,提高了代码的可读性。星火大模型评价,“总体来说,这段代码的注释质量较高,能够提供足够的信息供其他开发者理解和使用该类。”

FuncGPT(慧函数)现免费使用,下载链接:https://c.suo.nz/d88yp

【版权声明】本文为华为云社区用户原创内容,转载时必须标注文章的来源(华为云社区)、文章链接、文章作者等基本信息, 否则作者和本社区有权追究责任。如果您发现本社区中有涉嫌抄袭的内容,欢迎发送邮件进行举报,并提供相关证据,一经查实,本社区将立刻删除涉嫌侵权内容,举报邮箱: cloudbbs@huaweicloud.com
  • 点赞
  • 收藏
  • 关注作者

评论(0

0/1000
抱歉,系统识别当前为高风险访问,暂不支持该操作

全部回复

上滑加载中

设置昵称

在此一键设置昵称,即可参与社区互动!

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。