Условные обозначения для сводки и текста параметров?

Question

Для написания резюме и текста параметров, есть ли лучший способ выяснить, сколько деталей вы должны изучить, использовать ли целые предложения или нет?Я просто ищу какие-то хорошие привычки, чтобы начать их использовать.Спасибо!

public class JustinBieber{
    private readonly bool HasTalent;
    JustinBieber(){
        HasTalent = false;
    }

    /// <summary>
    /// JustinBieber object sings a song in specified style
    /// </summary>
    /// <param name="songName">The song to be sung</param>
    /// <param name="style">The style in which the song is sung</param>
    public void SingSong(string songName, string style){
        ...
    }
} 

Answer 1

Мое эмпирическое правило здесь состоит в том, чтобы использовать достаточно деталей, чтобы ясно передать смысл, и не более.

Я предпочитаю краткость здесь - и считаю, что это особенно важно, поскольку документация XML используется для intellisense.Очень длинные комментарии, как правило, там не всегда видны, поэтому я бы их избегал и помещал «более длинные» комментарии в <remarks>, если это необходимо.