Документирование геттеров и сеттеров

Question

Для простых геттеров/сеттеров, как показано ниже, как лучше всего его документировать?

public float getPrice() 
{ 
    return price; 
} 

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

Вариант 1:

/** 
* Get the price field. 
* 
* @return 
*/ 

Вариант 2:

/** 
* @return Price 
*/ 

Или не документировать его вообще?

Answer 1

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

/** 
* Simple getter. 
* @return Price 
*/ 

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

Answer 2

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

Answer 3

Я искал стандартный способ DOCO функции пока я искал SO и нашел людей, использующих: GhostDoc - http://submain.com/products/ghostdoc.aspx

Это один из лучших инструментов автоматического DOCO там и форматы каждый из ваших комментариев так же, как , Самое лучшее в этом - это то, что ваши методы точно названы, тогда вам даже не нужно редактировать автоматически созданный doco, поскольку это будет иметь смысл.

Кроме того, комментарии возникают, когда вы используете intellisense, чтобы вы могли напомнить о том, что ваш код делает через месяц после того, как вы его написали! :)

GhostDocs сделает это к Вашей собственности: (ярлык Ctrl + Shift + D)

/// <summary> 
    /// Gets the price. 
    /// </summary> 
    /// <returns></returns> 
    public float getPrice() 
    { 
     return price; 
    } 

Answer 4

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

Я хотел бы использовать это:

/** 
* @return the price. 
*/ 

или

/** 
* Returns the prize. 
* 
* @return the price. 
*/ 

Это дублирует тот же текст, но это может быть необходимо, если вы согласились на определенные стандарты кодирования, которые требуют описания и не только теги.

Я бы не сказал, что он возвращает цену поле, так как это описывает внутреннее представление.

Answer 5

Если «цена» - это что-то иное, чем самое очевидное значение, то ваш комментарий должен описывать, что означает «цена» и используется, а не только то, что оно называется.

Некоторые гипотетические примеры:

• ли это «цена до уплаты налогов» или «цена, включая налог»?
• Это выражено в долларах, евро или фунтах?
• Он округлен до ближайшего цент, 5 центов или долларов?
• Это специальное значение, возвращаемое для указания свободного элемента (например, 0.0f)?
• Может ли цена быть «неинициализированной», и если да, какое значение возвращается (например, -1.0f)?

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

В случае «простых» значений, которые полностью не требуют пояснений (например, Rectangle.Width), то не тратьте время на ввод текста - AtomineerUtils создаст этот уровень документации для вас одним нажатием клавиши. (Преимущество AtomineerUtils в вашем случае состоит в том, что он поддерживает форматы комментариев XML Doxygen, Javadoc и Documentation и VB, C#, C++/CLI, C++ и C, поэтому вы можете сохранить свой существующий формат, в то же время значительно сократить время, затрачиваемое на Документация по документации GhostDoc будет выполнять аналогичную работу, но она поддерживает только документацию Xml для VB и C#)