Как вы оформляете основные и второстепенные комментарии? - PullRequest
Новая
       42

Как вы оформляете основные и второстепенные комментарии?

7 голосов
/ 01 января 2009

Иногда я хочу написать «основной» комментарий для описания большого блока кода, а затем написать «второстепенные» комментарии для описания нескольких строк в этом блоке кода: 

// Major comment

// Minor comment
...

// Minor comment 2
...

Основной комментарий выглядит странно без кода под ним, и вы не можете визуально сказать, сколько кода он описывает ниже.

Как вы оформляете эти комментарии?

(я помню, как читал об этом в Code Complete некоторое время назад, но мне не принадлежит книга.)

Ответы [ 12 ]

0 голосов
/ 01 января 2009 
// A plate is displayed if a WorkFlowStepUpdate message is received
// whose:
//        * Change_Type is License_No
//        * Event_Type is GA, NA, or NG
//        * New_Value is non-null and non-blank
//        * Inspection_DateTime<(NOW-TimeInMinutesBeforeExpiringDisplaySignMessage)
//
// A plate is removed:
//         * if it has been displayed for TimeInMinutesBefore...
//         * a GA, NA, or NG CloseEvent is received  whose New_Value matches
//           a displayed plate
//
// If a plate is to be added to a full screen, the oldest plate on the display
// is removed to make room for the new plate.


.
.
.
.
.



// Record the ping status of each IP device
foreach (string s in th.Keys)
        {
        // We don't know if this is a wks or svr.
        // But we can rely on 0 being bad, and we'll
        // get the 'proper' state enumeration down in GetsOHInfo
        // 
        if (IsItLive(s)) IPStates[s] = 1;
        else IPStates[s] = 0;
        IPTimes[s] = System.DateTime.Now.ToUniversalTime();
        }
0 голосов
/ 01 января 2009

Я бы сделал это, возможно, так: 

// Here we do it
//
// So, be aware this text is just to make a silly
// long comment to show how it would look like 
// in real code. 
doTheRealThing();

// and this is another thingy
doOtherThing();

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

// prepare for party
doIt();

// Here we do it
//
{
    // So, be aware this text is just to make a silly
    // long comment to show how it would look like 
    // in real code. 
    doTheRealThing();

    // and this is another thingy
    doOtherThing();
}

// another code that is not really affected by the comment
// above
die();

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

/**
 * This function will return the current object.
 *
 * And now it follows the normal long stuff that's again
 * a bit stretched to fill space...
 */
Object getCurrentObject();

Для некомментируемых диапазонов кода, я явно не использую эти комментарии, так как я резервирую их только для кода документа. Я собираюсь использовать 

#if 0
    Code in Here that's disabled
#endif

И это также избавит меня от некоторых вещей, которые не являются допустимым кодом C ++ (вещи между этими разделителями по-прежнему должны содержать действительные токены). Я не уверен, как обстоят дела с этим в C #.

Страница:
...