Что поместить в комментарии метода, представляющего действие?

Question

Я всегда спрашиваю себя об этом, и я думаю, что пришло время услышать некоторые мнения, что я должен добавить в комментарии моих методов, которые представляют определенные действия?

Я должен объяснить что? Прокомментировать что?

В настоящее время я ничего не комментирую, потому что не знаю, что поставить.

Edit:

Вы не понимаете, о чем я спросил, возможно, потому что я не очень хорошо объяснил, я хочу знать, что добавить в комментарии методов, представляющих действие (действие Контроллера). Пример (в PHP):

<?php
class UserController  {

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

    }

}
?>

Answer 1

Прежде всего, не пишите комментарии, рассказывающие о том, что делает метод.

Для этого есть две причины: во-первых, он делает все загроможденным комментариями и его труднее читать, чем просто кодсам.Подобные комментарии

i++; //increment i

бессмысленны.Во-вторых, эти комментарии станут устаревшими, когда вы будете поддерживать код, а поддержка комментариев - это чрезмерно загруженная работа, которую вы не хотите делать.Если вы напишите так много комментариев, что вам придется их поддерживать, комментарии станут активно вредными , потому что они не соответствуют тому, что делает код

i-= 2; //increment i

Ваша цель должна состоять в том, чтобы написатьясный, понятный код с описательными именами, чтобы люди могли читать его, не полагаясь на комментарии.

Если вы прокомментируете свои методы, документируйте, для чего предназначен метод , недокумент, как метод делает то, что он делает - это то, что делает код.Вы должны комментировать вещи, которые не очевидны для людей, читающих код, вы должны комментировать то, что код должен делать, но не забывайте комментировать низкоуровневые детали кода.

Answer 2

ИМХО, комментарий к контроллеру должен содержать две вещи:

1. Как вы получите это действие: какой метод запроса (POST, GET, другие) и какой URL.
2. Очень краткое изложение того, что он делает (а не «как»).

Дело в том, что вам не нужно писать абзац подробностей, потому что имя вашей функции должно уже указывать, что она делает (что в действиях Контроллера несколько ограничено соглашением, таким образом, второй пункт),И содержащий код должен быть достаточно коротким, чтобы его можно было легко пропустить, и достаточно подробным, чтобы объяснить «как» часть.

На самом деле видео ^[51:20] связанные с предметом.Хотя, я думаю, что правило UncleBob о 3..5 строках слишком жесткое.В действии контроллеров много приготовлений , но ~ 4 строки, которые выполняют реальную работу, должно быть достаточно.

Answer 3

Если вы не знаете, что поместить для комментария метода, это часто говорит о том, что вы не совсем понимаете, что вы хотите, чтобы метод делал.В противном случае вы могли бы описать это.

Подумайте об этом так.Представьте, что вы отложили приложение на 2 года, а затем снова посмотрели на него.Опишите себе, что должен делать этот метод.

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