Должны ли комментарии .net начинаться с заглавной буквы и заканчиваться точкой?

Question

В зависимости от того, какую обратную связь я получу, я мог бы поднять этот «стандарт» со своими коллегами. Это может стать пользовательским правилом StyleCop. там уже один написан?

Итак, Stylecop уже предписывает это для тегов документации summary, param и return.

Как вы думаете, имеет ли смысл требовать того же от комментариев?

Относительно примечания: если комментарий уже длинный, то должен ли он быть написан как правильное предложение?

Например (возможно, я слишком старался проиллюстрировать плохой комментарий):

//if exception quit

против

// If an exception occurred, then quit.

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

//if exception quit
if (exc != null)
{
    Application.Exit(-1);
}

и

// If an exception occurred, then quit.
if (exc != null)
{
    Application.Exit(-1);
}

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

Пожалуйста, подтвердите свое мнение. У вас есть хорошие рекомендации по искусству комментирования, особенно если это относится к .Net?

Спасибо.

Answer 1

Если коду нужен комментарий, он должен быть правильно сформирован, потому что в IMO, вероятно, есть (нетривиальная) концепция, требующая пояснения

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

Answer 2

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

// SERVER

Поскольку среда IDE раскрашивает комментарии, иногда удобно иметь такие короткие комментарии, чтобы помочь в умственной блокировкевещи на сегменты.Я обычно делаю это только для дюжины строк кода.Если он длиннее, то #region кажется лучше.

Я также часто пишу заметки в своих комментариях, иногда в качестве ссылки для себя, например:

// NOTE: -273.15 is absolute zero in °C, used for a MinValue below

Это не грамматически красивое или полное предложение, но оно имеет смысл.

Где я склонен использовать более полные, структурированные предложения, в кратком изложении моих методов, например:

/// <summary>
/// Populates the properties of a Sensor object based on
/// the XML components of its data file.
/// </summary>

Те, кого я чувствую, более вероятно, будут прочитаны кем-то еще, и это помогает иметь многословие и чистое форматирование.

Answer 3

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

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

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

Answer 4

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

Answer 5

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

    /// <summary>
    /// you summary here
    /// </summary>
    /// <param name="param1">Describe parameter usage</param>
    /// <param name="param2">Describe parameter usage</param>