Форматирование исходного кода

Введение

Языки программировния не требует от программиста придерживатся каких либо строгих правил форматирования кода, а требуется только соблюдение синтаксиса. Но тем не менее существуют негласные правила и даже несколько стандартов форматирования исходного кода. В чем же дело? Для чего же себе усложнять жизнь каким либо правилами, если все и так работает? Ответ совершенно прост, любой код намного чаще читают чем пишут! А не форматированный код это не удобно, является причиной того что допущенная ошибка не будет замечена, требует титанических усилий для поиска в нем нужного участка и разбора что там написано да и просто некрасиво! Исходя из изложенного, код требует форматирования для удобного и легкого последующего чтения, ну и конечно чтобы требовало минимум дополнительных усилий на процедуру форматирования.

Общие советы.

старайтесь не использовать сокращения слов и абривиатуры, кроме общепринятых, все время помните что, то что вы пишете придется читать либо Вам либо кому то другому. Уверен что через 3-6 месяцев вы врядли вспомните что wwc это wrong word counter (счетчик неправильных слов);
давайте переменным и функциям осмысленные, отвечающие реальным целям названия. (название функции MakeJob совершенно не о чем не говорит);
старайтесь не вносить в название избыточную информацию (в классе реализующем массив строк переменную содержащую количество элементов достаточно будет назвать ElementCount, а название StringArrayElementCount явно будет избыточным);
используйте простые и желательно короткие, общеизвестные слова для названий;

Использование стилей регистра букв

Паскаль

При использовании этого стиля все первые буквы слов входящих в название пишутся в верхнем регистре.

WrongWordCounter

Кэмел

При использовании этого стиля вверхнем регистре пишутся только первые буквы 2-го и последующих слов (подходит для тех кто не использует Венгерскую нотацию т.к. будет трудно читать суфиксы).

wrongWordCounter

GNU

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

wrong_word_counter

Оформление кода

для формирования отступов всегда используйте табуляцию, почти все редакторы кода для языка C содержат настройку по количеству вставляемых отступов вместо знака табуляции;
в остальных случаях кроме первого отступа, используйте пробел;
если строка по ширине не помещается на экране (это около 80 символов или меньше если редактор занимает не всю ширину экрана) продолжение строки переносите на следующую строку, т.е. код должен быть виден без использования горизантальной прокрутки;
отделяйте логические блоки кода одной или двумя пустыми строками (т.е. описали переменные вставьте пустую строку, инициализировали переменные вставьте еще одну пустую строку и т.д.);

Фигурные скобки.

Существует и используется несколько стилей растановки фигурных скобок в исходном коде:

Рациональный стиль, предложенный Керниген (Kernighan) и Ричи (Ritchie), авторами языка C. При использовании этого стиля экономится вертикальное пространство, но относительно трудно находить открывающую скобку "{"

    if( i > 0 ){
        i++;
        ...
        return 1;
    }
Стиль Whitesmith. Whitesmith являлся разработчиком компилятора C. Хорошо выделяет блок кода, но скобки сразу не найдеш.

   if( i > 0 )
        {
        i++;
        ...
        return 1;
        }
Стиль Олмена. Эрик Олемен (Eric Allman) разрабатывал утилиты Unix и BSD одна из которых Sendmail (межсетевой почтовый роутер) в дальнейшем один из основателей фирмы Sybase, ладно разговор не про него. Так как Олмен использовал этот стиль, в коде который был довольно известен, стиль приобрел довольно широкое распространение. Также этот стиль часто называют "стиль BSD". На мой взгляд этот стиль самый удобный и читабельный.

    if( i > 0 )
    {
        i++;
        ...
        return 1;
    }
Стиль GNU. стандарт GNU предписывает придерживатся следующего вида похожего на смесь стиля Олмена и Whitesmith

int func1(int i)
    {
        if( i > 0 )
        {
            i++;
            ...
            return 1;
        }
    }

Используйте блок из фигурных скобок для одной строки

    if( i > 0 )
    {
          j++;
    }
    else
    {
        j--;
    }

хотя в данном случае, все будет ясно и прекрасно работать и в оформлении без скобок

    if( i > 0 ) j++;
    else         j--;

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

Выделение выражений.

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

Не ставьте пробел после операторов if, for, while и т.д. Синтаксис стандартный и запутатся трудно, а время и место экономится;

    if( выражение )

    for( ... ; ... ; ... )

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

if( i > 5 ) или if( (x - 25 > dx) && ( y - 40 > dy ) && (x > 0) && (y > 0 )

выглядит намного лутше чем

if(i>5) или if(x-25>dx && y-40>dy && x>0 && y>0)

даже в такой простой строке при неправильном написании ум начинает бунтовать и намекать "а не пошел ты куда подальше... с такими выражениями"
Имеет смысл операторы, такие как =, >,<, !=,== и т.д. с двух сторон отделяйть пробелами

i = 5; или j = l + 6 или (ErrorCount + WarningCount) > MaxMessage

конечно можно писать и так

i=5; или j=l+6 или ErrorCount+WarningCount>MaxMessage
Отделяйте передаваемые в функции параметры пробелами

ShowWindow( SW_HIDE ); или GetWindowRect( &theApp.rWinPos );

несколько хуже выглядит

ShowWindow(SW_HIDE); или GetWindowRect(&theApp.rWinPos);

и это заметно даже при одном параметре, что же говорить когда параметров больше и где начинают перемешиватся кони и люди :)

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