// I usually write comments like this
Там, где я работаю, требуется использовать стандартный стиль комментариев xml для большинства объявлений (классов, методов, некоторых свойств) (мы используем C #).
Иногда вы можете увидеть комментарии верхнего / нижнего колонтитула в использовании.
/****************************************************/
// Filename: Customer.cpp
// Created: John Doe
// Change history:
// 18.12.2008 / John Doe
// 14.01.2009 / Sara Smith
/****************************************************/
/* Here goes a lot of stuff */
/****************************************************/
// EOF: Customer.cpp
/****************************************************/
Нечто подобное использовалось на одном из моих старых рабочих мест. На мой взгляд слишком много ненужных вещей. История изменений хорошо видна в наши дни благодаря системе контроля версий.
Во многих хороших магазинах программного обеспечения есть внутренние инструкции относительно того, когда и как писать комментарии. Документы обычно называют «политикой стиля исходного кода» или чем-то подобным. При комментировании кода очень важно придерживаться одного общего стиля.
Конечно, эта комментирующая шумиха не должна заходить слишком далеко, чтобы комментировать каждый маленький кусочек кода, особенно очевидный.
/// <summary>
/// Handles the standard PageLoad event
/// </summary>
/// <param name="sender">
/// Event sender
/// </param>
/// <param name="e">
/// Event arguments
/// </param>
public void Page_Load (object sender, EventArgs e)
{
// Do something here
}
Это хороший пример чрезмерной одержимости комментированием. Нечто подобное добавляет ровно ноль информации, но только добавляет шум в исходный файл. И мы должны делать это на работе по мере необходимости.
Мое личное мнение - добавлять комментарии, когда вам есть что сказать или объяснить, а не только ради того, чтобы все комментировать.