Комментарии¶
Ко всех публичным классам должны быть написаны комментарии.
Обязательны к комментированию:
- сами классы/enum/делегаты
- публичные методы
- публичные свойства
Общие требования¶
Комментарии пишутся на английском или русском языках¶
Зависит от проекта. Но в проекте все должно быть на одному языке.
В конце комментария должна быть точка¶
Мотивация
Соответствуем рекомендация от Microsoft.
Комментарии должны быть xml, а не простыми комментариями на C¶
Неправильно
// key for account activation
public string ActivationKey { get; set; }
Правильно
/// <summary>
/// Key for account activation.
/// </summary>
public string ActivationKey { get; set; }
У методов и конструкторов также должны быть комментарии к:¶
- аргументам
- возвращаемым значениям
- типам, если класс/метод -
generic
При наследовании или реализации интерфейсов следует наследовать документацию с помощью inheritdoc:¶
/// <inheritdoc />
public class YandexPaymentOptions : IYandexPaymentOptions
{
/// <inheritdoc />
public long YandexShopId { get; set; }
}
Комментарии методов должны быть в 3-ем лице¶
Неправильно
/// <summary>
/// Проверка опциий и возврат списка ошибок.
/// </summary>
/// <returns>
/// Список ошибок. Если опции валидны, список будет пустым.
/// </returns>
public IReadOnlyCollection<ConfigValidationError> Validate(string prefix = null);
Правильно
/// <summary>
/// Проверяет валидность опциий и возвращает список ошибок.
/// </summary>
/// <returns>
/// Список ошибок. Если опции валидны, список будет пустым.
/// </returns>
public IReadOnlyCollection<ConfigValidationError> Validate(string prefix = null);