Комментарии .NET должны запуститься с прописной буквы и закончиться периодом?
В зависимости от обратной связи я добираюсь, я мог бы повысить этот "стандарт" со своими коллегами. Это могло бы стать пользовательским правилом 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?
Спасибо.
5 ответов
Я часто пишу комментарии, которые просто призваны помочь мне найти участки кода. (Например:
// SERVER
Поскольку IDE выделяет комментарии цветом, иногда удобно иметь такие короткие комментарии, чтобы мысленно разделить код на сегменты. Обычно я делаю это только для дюжины или около того строк кода. Если код длиннее, то лучше использовать #region.
Я также часто пишу примечания в комментариях, иногда в качестве справки для себя, например, так:
// ПРИМЕЧАНИЕ: -273.15 - абсолютный ноль в °C, используется для MinValue ниже
Это не грамматически красивое или полное предложение, но оно имеет смысл.
Где я обычно использую более полные, структурированные предложения, так это в кратком описании моих методов, например, вот так:
/// <summary>
/// Populates the properties of a Sensor object based on
/// the XML components of its data file.
/// </summary>
Эти предложения, как мне кажется, с большей вероятностью будут прочитаны кем-то другим, и здесь помогает многословие и чистое форматирование.
Если коду нужен комментарий, он должен быть хорошо сформирован, потому что в IMO, вероятно, есть (нетривиальная) концепция, которая требует объяснения.
Следует избегать банальных комментариев, например, в ваших примерах. Они ничего не добавляют, кроме шума.
Никогда не тратится время на написание четких, читаемых, понятных комментариев. Сколько раз я позже перечитывал свои собственные комментарии только для того, чтобы с трудом их понять. Люди, которые пишут неряшливые или плохо оформленные комментарии, часто используют те же черты в своем коде.
Я обнаружил, что когда я пытаюсь быть кратким в комментариях (т.е. неполные предложения, фрагменты), я часто опускаю ключевые предположения или слова, которые на самом деле прояснили бы смысл. Мне сейчас трудно придумать конкретный пример, извините.
В целом, однако, принуждение себя писать полные, правильные предложения также заставляет вас больше думать о том, что вы действительно пытаетесь сказать комментарием. Я часто ловил себя на том, что переосмысливаю то, что я действительно хочу включить в комментарий, написав его полностью.
Нет никаких веских причин жертвовать ясностью на алтарь краткости. Кому-то в будущем понадобится понять код. Комментарии предназначены для них, поэтому сделайте их понятными.
если вы комментируете методы в visual studio, вам следует рассмотреть возможность использования summary и params в верхней части метода. Так вы получите подробную информацию о методе во время завершения кода. Вот пример
/// <summary>
/// you summary here
/// </summary>
/// <param name="param1">Describe parameter usage</param>
/// <param name="param2">Describe parameter usage</param>