Php 在表示操作的方法的注释中放置什么？

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

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

目前我没有评论任何事情，因为我不知道该说什么

编辑：

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

---

首先，不要写注释来说明该方法的作用

这有两个原因，第一，它让所有的东西都被注释弄得乱七八糟，而且比代码本身更难阅读。这样的评论

i++; //increment i

这些都是毫无意义的。其次，当您维护代码时，这些注释将变得过时，维护注释是您不想做的过于繁忙的工作。如果你写了太多的注释，你不得不维护它们，这些注释将变得非常有害，因为它们与代码的功能不一致

i-= 2; //increment i

您的目标应该是用描述性名称编写清晰易懂的代码，这样人们就可以阅读代码而不必依赖于注释

---

如果您确实对方法进行了注释，记录该方法的目的是什么，不要记录该方法是如何完成其功能的——代码就是这样做的。您应该对阅读代码的人看不清楚的内容进行注释，您应该对代码应该做的事情进行注释，但请记住不要对代码的低级细节进行注释。

首先，不要写注释来说明该方法的作用

这有两个原因，第一，它让所有的东西都被注释弄得乱七八糟，而且比代码本身更难阅读。这样的评论

i++; //increment i

这些都是毫无意义的。其次，当您维护代码时，这些注释将变得过时，维护注释是您不想做的过于繁忙的工作。如果你写了太多的注释，你不得不维护它们，这些注释将变得非常有害，因为它们与代码的功能不一致

i-= 2; //increment i

您的目标应该是用描述性名称编写清晰易懂的代码，这样人们就可以阅读代码而不必依赖于注释

---

如果您确实对方法进行了注释，记录该方法的目的是什么，不要记录该方法是如何完成其功能的——代码就是这样做的。您应该对阅读代码的人看不清楚的内容进行注释，您应该对代码应该做的事情进行注释，但请记住不要对代码的低级细节进行注释。

如果您不知道如何对方法进行注释，这通常意味着你没有完全理解你想要这个方法做什么。否则，您将能够描述它

---

这样想吧。想象一下，您将应用程序搁置两年，然后再次查看它。向你未来的自己描述一下这个方法应该做什么。

如果你不知道该给一个方法添加什么注释，这通常表明你不完全理解你想要这个方法做什么。否则，您将能够描述它

---

这样想吧。想象一下，您将应用程序搁置两年，然后再次查看它。向你未来的自己描述这个方法应该做什么。

我喜欢用尽可能多的信息来填充我的评论，这样当以后我的整个程序停止工作时，我可以返回并找出一个函数在做什么，为什么它在做，为什么它不做其他事情。缺点是，正如其他人所指出的，这意味着每次更新代码时都必须更新注释。然而，只要你的评论是有帮助的，这是一个有效的成本

/**
* 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++
};

---

我喜欢用尽可能多的信息来填充我的评论，这样当我的整个程序停止工作时，我可以返回并找出一个函数在做什么，为什么它在做，为什么它不做其他事情。缺点是，正如其他人所指出的，这意味着每次更新代码时都必须更新注释。然而，只要你的评论是有帮助的，这是一个有效的成本

/**
* 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++
};

---

IMHO，控制器的注释应包含两个内容：

如何执行此操作：哪个请求方法（

POST

，

get

，其他）以及URL是什么

非常简短地总结了它的作用（而不是“如何”） 问题是，您不需要编写一段详细信息，因为您的函数名应该已经说明了它的功能（在控制器操作中，这在某种程度上受到约定的限制，因此是第二点）。而且，包含的代码应该足够短，可以轻松跳过，并且足够详细，可以解释“如何”部分

---

实际上，有一个与主题相关的问题。不过，我认为Bob关于3..5行的规则有点太苛刻了。在管制员的行动中有很多准备工作，但实际工作的4行就足够了。

IMHO，对管制员的评论应该包含两件事：

如何执行此操作：哪个请求方法（

POST

，

get

，其他）以及URL是什么

非常简短地总结了它的作用（而不是“如何”） 问题是，您不需要编写一段详细信息，因为您的函数名应该已经说明了它的功能（在控制器操作中，这在某种程度上受到约定的限制，因此是第二点）。而且，包含的代码应该足够短，可以轻松跳过，并且足够详细，可以解释“如何”部分

实际上，有一个与主题相关的问题。不过，我认为Bob关于3..5行的规则有点太苛刻了。行动中有很多准备工作