代码注释用什么字体注释好_用更好的代码替换注释

最新推荐文章于 2023-09-25 11:20:33 发布

dfsgwe1231

最新推荐文章于 2023-09-25 11:20:33 发布

阅读量827

点赞数

文章标签： java python linux 人工智能大数据

原文链接：https://hackernoon.com/replace-comments-with-better-code-2u6v3y3n

版权

代码注释用什么字体注释好

嗨，我是意大利的软件工程师Valerio。

在过去的十年中，我曾在任何类型的公司和同事中担任软件工程师。

软件开发本质上是协作的。如果您在一家公司工作，无论规模大小，您显然都在与他人合作。

我强烈认为注释是某些功能或整个类的文档，因为它们可以通过两种方式帮助开发人员：

使用注释导航代码以引导IDE行为；
添加更多上下文信息，以避免对为什么以这种方式设计代码块产生误解（增加性能，解决错误等）。

当您是团队的一员时，代码中的注释会引起讨论和分歧。让我们同意“ 代码中的注释 ”的概念。

<?php

public function calc () 
  {
  // Add b to a 
  $c =  $this ->a +  $this ->b;

  // return the result of a + b 
  return  $c;
}

上面的结果可能是会议的结果，在会议中，建议团队为代码添加注释。

重复执行代码是最糟糕的事情，添加注释以描述代码的行为，这将使阅读代码本身更加清晰，这意味着您在浪费时间，其他开发人员也将花费时间进行调查，除非提供文档。

初级开发人员依靠注释来讲述故事，何时应该依靠代码来编写故事。经验不足的开发人员倾向于使用注释来描述代码块背后的故事。

我们甚至可以更富有表现力地照顾类，函数和变量的名称，而无需写任何注释。

如果您需要编写注释来解释您的功能是什么，那么您需要做的第一件事就是考虑重组您编写的代码以使其解释其用途的可能性。看下面的例子：

<?php

/**
 * Calculate spending limit by customer income and try to find a room to a lower price.
 */
public function rentRoom ($income)
 {
    $spending = round(($income* 0.15 ) / 12 );
    foreach ( $this ->rooms as $room) {
        if ($room->price <= $spending) {
            return $room;
        }
    }
    throw new RoomNotFoundException();
}

仅一条评论行是可以接受的。还是我们可以审查代码以使其更清晰，模块化并避免任何评论？

<?php

/**
 * Rent a room based on customer's income
 * 
 * @params integer $income
 */
public function rentRoom ($income)
 {
    try {
        $this ->findRoomByPriceLimit(
            $this ->calculateCustomerSpending($income)
        );
    } catch (\Eception $exception) {
        // do something with error
    }
}


public function findRoomByPriceLimit ($limit) 
 {
    foreach ( $this ->rooms as $room) {
        if ($room->price <= $limit) {
            return $room;
        }
    }
    throw new RoomNotFoundException();
}


public function calculateCustomerSpending ($income, $percentage = 15 )
 {
    return round(
        ($income*($percentage/ 100 )) / 12
    );
}

代码更加冗长，无需注释。

这些数字现在有一个标签，并且这些功能都有一个清楚地说明其作用的名称。如果单独考虑，此示例可能看起来有点多余。您需要集中精力的是策略，即使用代码本身解释如何以及为何在其中找到该代码的价值。

我的建议是不要低估这方面。如果代码中的注释过多，您和其他开发人员将不太注意他们的存在的风险将成倍增加，并且还会在文档中传播旧的和错误的信息。