喝咖啡休息#79。Java 开发人员犯下的 10 个阻碍他们取得成功的错误。编写有意义的代码注释的开发人员指南

Java 开发人员犯下的 10 个阻碍其成功的错误

来源：Dev.to 根据我的经验，我列出了开发人员所犯的 10 个阻碍他们取得成功的错误：

1. 不要编写单元测试

不编写单元测试的开发人员会在代码中犯更多错误。这导致产品不稳定和客户不满意。

2.他们不会手动检查代码

即使你用单元测试完全覆盖了你的代码，你仍然有可能错过一些东西。始终建议在提交代码供审核之前手动测试您的代码。这样您就可以在开发阶段检测到错误。

3.他们认为：“这永远不会发生。”

开发人员在编写新代码时经常会犯错误，认为某些场景永远不会发生。最终事实证明他们错了。处理所有可能执行代码的场景。防御性编程方法将帮助您解决这一问题。

4. 得不到反馈

定期征求其他开发人员和用户的反馈。与您的同事分享您的意见。

5. 他们不检查代码的功能。

开发人员经常编写代码，但不检查其功能。因此，当代码投入生产时，会产生各种问题。

6.编写长的程序代码

编写具有大量逻辑的长方法非常容易。通过这样做，程序员可以在许多地方实现相同的逻辑。具有大量小方法的项目具有更好的代码重用性并且更容易维护。

7.他们不了解工具

工具是你双手的延伸。您对它们了解得越多，您的工作效率就越高。您应该非常熟悉您正在使用的 IDE。学习快速命令，总有一些命令可以帮助您提高工作效率。在 IntelliJ IDEA 中，这些是 Sonar Lint、Spot bugs 和 Code Metrics。

8.忽略代码中的问题

开发最成功产品的开发人员不断地更改代码。不要害怕重构你的代码。如果您的代码经过单元测试，则回归的可能性很小。开发人员经常忽略有问题的代码。作为开发人员，您有责任维护应用程序的良好状态。因此，请解决您发现的任何问题。

9. 他们编码时没有意识到后果。

开发人员切勿在不了解后果的情况下更改代码并将其发布到生产环境中。该代码可以为给定的测试值生成正确的结果。然而，在某些情况下，这可能会导致不可预测的结果并产生严重的问题。当开发人员使用他们不完全理解的库中的函数时，经常会发生“不可预测”的编码。当开发人员在不了解解决方案的情况下解决问题时，也会发生这种情况。

10.不要寻求帮助

开发人员不是很善于交际的人。他们喜欢自己解决问题。但是，一个开发人员自己从头到尾创建一个产品的时代已经结束了。软件开发是一项团队活动。当你在编程时遇到问题时，尝试自己解决。但如果找不到解决方案，请不要浪费太多时间。您的一些同事很可能已经遇到了同样的问题并且知道解决方案。这将节省时间并提高生产率。

编写有意义的代码注释的开发人员指南

来源：Stepsize 在大多数情况下，您并不是唯一一个从事同一项目或代码库的人。这意味着其他人必须理解您的代码。代码注释也是如此。开发人员经常在没有太多背景的情况下写出“快速而肮脏”的评论，让他们的同事对作者想说什么感到困惑。这是不好的做法，会造成更多的混乱而不是清晰。 拥有清晰的代码注释可以帮助其他开发人员。描述函数、其基本原理、输入和输出的代码注释可以加快其他开发人员的学习过程。另一方面，代码注释让我们想到一个问题：值得编写它们吗？有相当一部分开发人员反对编写代码注释。原因是他们认为代码是不言自明的。如果其他开发人员无法通过查看代码来理解代码的用途，那么它就是糟糕的代码。也许这是真的。但想想注释掉代码所需的小努力以及它带来的潜在好处。代码注释对于加快任何开发人员（尤其是初级开发人员）的入门过程非常重要。让我们看看不同类型的代码注释。

1. 对文档的评论。

此类注释的主要目的是快速阐明文件或组件的用途。您可以在“index”文件的顶部添加代码注释，而不是阅读组件的整个代码来了解它的功能。这将有助于解释该组件的作用。我不太喜欢这种类型的注释，因为它使代码有点混乱。我认为这些类型的架构注释应该位于您的内部文档中，您可以在其中集中维护和讨论项目的架构。然而，开源项目确实需要它们。

2、功能注释。

这是最有用的评论类型。它们描述了函数的目的、参数和输出。

/**
 * @desc Creates a welcome message
 */
function sayHello(name) {
    return `Hello ${name}`;
}

3、逻辑性的评论。

这些是函数内的注释，用于阐明复杂的代码路径。正如您可能已经猜到的，此类注释的存在表明您的代码过于复杂。此外，逻辑注释往往包含过多的详细信息。详细程度会造成更多混乱并降低代码的可读性。这是一个过于详细的代码注释的示例。

let date = new Date(); // store today's date to calculate the elapsed time

代码注释：4 种注释最佳实践

1.使用代码注释或标签

许多编程语言都定义了注释代码的标准。Java 使用Javadoc，而 JavaScript 使用JSDoc代码注释系统，许多文档工具都支持该系统。对于函数，您必须包含以下代码标签：

• @desc - 你的函数的描述
• @param - 函数接受的所有输入参数。请务必指定输入类型。
• @returns - 返回的输出。请务必指定输出类型。
• @throws 是函数可以抛出的错误类型。
• @example - 显示输入和预期输出的一个或多个示例。

下面是chunk函数的Lodash 代码示例。

/**
 * Creates an array of elements split into groups the length of `size`.
 * If `array` can't be split evenly, the final chunk will be the remaining
 * elements.
 *
 * @since 3.0.0
 * @category Array
 * @param {Array} array The array to process.
 * @param {number} [size=1] The length of each chunk
 * @returns {Array} Returns the new array of chunks.
 * @example
 *
 * chunk(['a', 'b', 'c', 'd'], 2)
 * // => [['a', 'b'], ['c', 'd']]
 *
 * chunk(['a', 'b', 'c', 'd'], 3)
 * // => [['a', 'b', 'c'], ['d']]
 */
function chunk(array, size = 1) {
  // logic
}

2. 解释你的行为的原因

许多开发人员使用注释来描述他们的代码的作用。执行此操作时，请务必说明创建特定功能或组件的原因。该信息称为上下文。上下文对于为开发人员提供有关功能或组件背后的设计决策的更多信息非常重要。当其他开发人员想要更改您的功能或组件时，上下文至关重要。下面您可以看到一个在没有上下文的情况下注释代码的糟糕示例。

/**
 * Sets the label property of a new form.
 *
 * @param label text for label of form
 */
function setFormLabel(label) {
    // logic
}

3.不要链接到其他文档或评论

不建议链接到其他代码注释或解释功能或组件的内部文档。

/**
 * Sets the label property of a new form.
 *
 * @see {@link https://myinternaldocument.com}
 */
function setFormLabel(label) {
    // logic
}

4. 编码时写注释

这似乎是显而易见的，但许多开发人员（包括我自己）忽视了这条规则。留下注释供以后使用是不好的，因为您可能会忘记您编写的一些逻辑，这将导致代码注释质量较低。如果您连续几天处理同一个拉取请求，则尤其如此。最好在刚刚完成一个功能或模块时写评论。请记住使代码注释尽可能简短。您不需要花费比编写代码本身更多的时间来编写注释。