Question

我总是这样问自己，我觉得是时候听一些意见了，我应该在代表某些行动的方法评论中加入什么？

我应该解释一下什么？评论什么？

目前我不评论任何事情，因为我不知道该放什么。

编辑：

你不理解我的问题，可能是因为我没有解释清楚，我想知道在表示动作的方法的注释中放什么（控制器的动作）。示例（在PHP中）：

<?php
class UserController  {

    /**
     * What to put here?
     */
    public function editAction() {

    }

}
?>

Answer 1

首先，不要写评论来说明方法的作用。

这有两个原因，首先，它使所有内容都被注释混乱，并且比代码本身更难阅读。像这样的评论

i++; //increment i

毫无意义。其次，当您维护代码时，这些注释将变得过时，并且维护注释是您不想做的过度繁忙的工作。如果你写了很多评论，你必须维护它们，那么评论将变得主动有害，因为它们与代码的内容不一致

i-= 2; //increment i

您的目标应该是使用描述性名称编写清晰易懂的代码，以便人们可以阅读它而无需依赖评论。

如果您对方法进行评论，记录方法的目的是，请不要记录方法的作用 - 这就是代码的作用。您应该对阅读代码的人不太明显的事情进行评论，您应该评论代码应该做什么，但只要记住不要评论代码的低级细节。

Answer 2

如果您不知道对方法的注释应该放什么，那通常表明您并不完全了解您希望该方法做什么。否则，您将能够描述它。

这样想。想象一下，你把应用程序放了2年然后再看一遍。向您的未来自己描述这种方法应该做什么。

Answer 3

恕我直言，对控制器的评论应该包含两件事：

您如何处理此操作：哪种请求方法（POST，GET，其他）以及URL是什么。
非常简要概述它的作用（而非“如何”）。

问题是，您不应该编写一段细节，因为您的函数名称应该已经说明了它的作用（在Controller中的操作在某种程度上受到约定的限制，因此第二点）。并且包含的代码应该足够短，以便于跳过，并且足够冗长以解释“如何”部分。

实际上有一个video ^[51:20]与主题相关。虽然，我认为UncleBob关于3..5行的规则有点过于苛刻。在控制器动作中有很多准备工作，但是做实际工作的~4行应该足够了。

Answer 4

我喜欢用尽可能多的信息来收集我的评论，所以当我的整个程序停止工作后，我可以回去查看函数正在做什么，它为什么这样做，以及它为什么不做别的。缺点是，正如其他人指出的那样，这意味着每次更新代码时都必须更新注释。但是，只要您的评论有用，这是有效的费用。

/**
* There are several different states which all DisplayObjects can      *
* be in. The majority of these are mouse events (over, out, click,     *
* press, release, scroll...), some are keyboard events (key press,     *
* key release, shift...) and the rest are implementation specific      *
* (ie. animations, cleaning the screen). Display objects which are     *
* created use these constants to create indexed Graphics objects, and  *
* then indexed cached canvases. Doing so allows for hot swapping of    *
* one context (ie. OVER) for another context (ie. OUT). This provides  *
* considerable performance increases (at the cost of increased memory  *
* and increased initial load times). Also, this provides a unified     *
* model of graphics. Therefore, Text, Shape, or Bitmap instances can   *
* all be created differently and rendered differently (via the child   *
* class specific render() function), then cached onto a back end       *
* canvas, at which point, they are all drawn onto the main canvas in a *
* similar fashion.                                                     *
* @property _contextID
* @protected
* @type Object
**/
var contextCounter = 0;
contextID = {
   ANIMATION     : contextCounter++,
   DEFAULT       : contextCounter++,
   CLEAN         : contextCounter++,
   CLICK         : contextCounter++,
   CLIP          : contextCounter++,
   COLLISION     : contextCounter++,
   DBLCLICK      : contextCounter++,
   DBLLDRAG      : contextCounter++,
   DBLLDRAGGING  : contextCounter++,
   DBLRCLICK     : contextCounter++,
   DBLRDRAG      : contextCounter++,
   DBLRDRAGGING  : contextCounter++,
   DRAG          : contextCounter++,
   DRAGGING      : contextCounter++,
   DROP          : contextCounter++,
   ENTER         : contextCounter++,
   INVALID       : contextCounter++,
   INVALIDDROP   : contextCounter++,
   LDRAG         : contextCounter++,
   LDRAGGING     : contextCounter++,
   LEAVE         : contextCounter++,
   LPRESS        : contextCounter++,
   LRELEASE      : contextCounter++,
   MOTION        : contextCounter++,
   RCLICK        : contextCounter++,
   RDRAG         : contextCounter++,
   RDRAGGING     : contextCounter++,
   RPRESS        : contextCounter++,
   RRELEASE      : contextCounter++,
   SCROLL        : contextCounter++,
   SCROLLIN      : contextCounter++,
   SCROLLOUT     : contextCounter++,
   TRPLCLICK     : contextCounter++,
   TRPLLDRAG     : contextCounter++,
   TRPLLDRAGGING : contextCounter++,
   TRPLRCLICK    : contextCounter++,
   TRPLRDRAG     : contextCounter++,
   TRPLRDRAGGING : contextCounter++,
   VALID         : contextCounter++,
   VALIDDROP     : contextCounter++
};

在代表行动的方法的评论中应该放什么？

4 个答案: