Используйте штриховую линию для зрительного разделения подпрограмм
Я всегда ставлю такой комментарий:
//---------------------------------------------------------
над каждым определением функции. (И к тому же, я не использую штриховую линию нигде более). Хотя пустые строки замечательно подходят для зрительного разделения блоков программы, исключительно их использование не дает эффекта. Штриховая линия между функциями облегчает их поиск. Так же как пустая строка указывает на границу абзаца, штриховые линии подобны заголовкам разделов. Если мне нужно еще более четкое разделение, то я использую:
//==========================================================
//ОПИСЫВАЮЩИЙ ТЕКСТ //==========================================================
Подумайте об этом, как о заголовке для главы. Я стараюсь не помещать никаких комментариев, за исключением штриховых линий, вне функции, потому что такие комментарии затрудняют обнаружение определений этой функции. При этом я форматирую функции следующим образом:
//---------------------------------------------------------
void descriptive_name( type descriptive_name )
{
// Если имена функции и аргументов недостаточно содержа-
// тельны, то я помещаю здесь комментарий, описывающий,
// что она делает. Я опускаю этот комментарий, если имена
// достаточно понятны. (Соответствующее правило гласит:
// "Не объясняй очевидного").
//
// Затем я описываю возвращаемое значение и аргумент.
// И вновь вы можете не использовать комментарий, если
// имена достаточно удачные.
//
// Наконец, я помещаю здесь комментарий, описывающий, как
// функция делает то, что она делает. И снова я пропускаю
// этот комментарий, если программа сама по себе достаточно
// содержательна.
code_goes_here();
}
