54.1. Форматирование
Исходный код форматируется с отступом на 4 позиции, с сохранением табуляции (т. е. символы табуляции не разворачиваются в пробелы). Для каждого логического уровня отступа добавляется одна табуляция.
Правила оформления (расположения скобок и т. д.) следуют соглашениям BSD. В частности, фигурные скобки для управляемых ими блоков if, while, switch и т. д. размещаются в отдельных строках.
Ограничьте размеры строк, чтобы код можно было читать в окне шириной 80 символов. (Это не значит, что никогда нельзя заходить за 80 символов. Например, не стоит разбивать длинную строку сообщения в произвольных местах, просто чтобы код умещался в 80 символов, так как это в результате скорее всего не сделает код более читабельным.)
Для единообразия кода не используйте комментарии в стиле C++ (комментарии //). Утилита pgindent заменит их на /* ... */.
Предпочитаемый стиль многострочных блоков выглядит так:
/* * текст комментария начинается здесь * и продолжается здесь */
Заметьте, что блоки комментариев, начинающиеся с первого символа, будут сохраняться утилитой pgindent как есть, но содержимое блоков комментариев с отступами будет переразбито по строкам как обычный текст. Если вы хотите сохранить разрывы строк в блоке с отступом, добавьте минусы следующим образом:
/*----------
* текст комментария начинается здесь
* и продолжается здесь
*----------
*/Хотя предлагаемые правки кода не обязательно должны следовать этим правилам форматирования, лучше их придерживаться. Ваш код будет пропущен через pgindent перед следующим выпуском, поэтому нет смысла наводить в нём красоту по другим правилам. Для правок есть хорошее правило: «оформляйте новый код так же, как выглядит существующий код вокруг».
В каталоге src/tools содержатся примеры файлов настройки, которые можно использовать с редакторами emacs, xemacs или vim для упрощения задачи форматирования кода в соответствии с описанными соглашениями.
Чтобы табуляция показывалась должным образом в средствах просмотра текста more и less, их можно вызвать так:
more -x4 less -x4
54.1. Formatting
Source code formatting uses 4 column tab spacing, with tabs preserved (i.e., tabs are not expanded to spaces). Each logical indentation level is one additional tab stop.
Layout rules (brace positioning, etc) follow BSD conventions. In particular, curly braces for the controlled blocks of if, while, switch, etc go on their own lines.
Limit line lengths so that the code is readable in an 80-column window. (This doesn't mean that you must never go past 80 columns. For instance, breaking a long error message string in arbitrary places just to keep the code within 80 columns is probably not a net gain in readability.)
To maintain a consistent coding style, do not use C++ style comments (// comments). pgindent will replace them with /* ... */.
The preferred style for multi-line comment blocks is
/* * comment text begins here * and continues here */
Note that comment blocks that begin in column 1 will be preserved as-is by pgindent, but it will re-flow indented comment blocks as though they were plain text. If you want to preserve the line breaks in an indented block, add dashes like this:
/*----------
* comment text begins here
* and continues here
*----------
*/
While submitted patches do not absolutely have to follow these formatting rules, it's a good idea to do so. Your code will get run through pgindent before the next release, so there's no point in making it look nice under some other set of formatting conventions. A good rule of thumb for patches is “make the new code look like the existing code around it”.
The src/tools directory contains sample settings files that can be used with the emacs, xemacs or vim editors to help ensure that they format code according to these conventions.
The text browsing tools more and less can be invoked as:
more -x4 less -x4
to make them show tabs appropriately.