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

[@novoselov]

"_" не исключение, для приватных полей следует использовать this.variable синтаксис.

[@Meroving]

это неправда. Во-первых, не путайте официальный гайдлайн с правилами хорошего тона. Устоявшихся традиций даже не две, а скорее три: с this, с underscore (_) и c m_. Последняя менее распространена, но ею, например, пользуется Рихтер.
Во-вторых, даже в официальном гайдлайне ничего не сказано о правилах именования приавтных полей. Пруф: msdn.microsoft.com/en-us/library/ms229012.aspx The naming guidelines for fields apply to static public and protected fields. You should not define public or protected instance fields.

[@novoselov]

SA1309: FieldNamesMustNotBeginWithUnderscore.
By default, StyleCop disallows the use of underscores, m_, etc., to mark local class fields, in favor of the ‘this.’ prefix.

Официальный гайдлайн не все читают, справедливости ради StyleCop тоже не все используют. Раньше сам писал m_, потом _, потом this. В Microsoft так-то бардак в исходных кодах привычное дело, так что проще положиться на инструмент который проверит и подскажет, чем на бумажный гайдлайн.

[@Teacher]

Угу, и имена методов с большой буквы в C#. Для и для имен булевых переменных, лично мне нравятся вопросительные предложения. Т.е. имя переменной не «done», а «isDone». Как то логичнее выглядит.

[@VolCh]

job.isDone — вопросительное предложение?

[@Teacher]

Во-первых, я говорил про переменные, а вы привели пример свойства/поля.
Во-вторых, да я считаю, что при чтении
if (job.IsDone)
лучше, чем
if (job.Done)
В-третьих, каждая команда вырабатывает свои соглашения, если вам больше нравится без Is, то это ваше право, просто надо всем придерживаться этого стиля и все…

[@VolCh]

В некоторых языках используется название именно «переменные объекта/класса», свойств/полей там нет. Но вообще я спросил, имея в виду, что в случае имени переменной/свойства/поля, то есть jobIsDone или job.isDone.isDone (сам такую форму предпочитаю) это утверждение, подразумевающее наличии какого-то объекта (не в смысле ООП, а в смысле существительного) могущее быть ложным или истинным, но не вопрос.

[@Cancel]

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

[@akzhan]

и тут же замечу, что однозначно фигово в Ruby то, что это касается только методов-геттеров.

1.9.3-p194 :001 > @done? = false
SyntaxError: (irb):1: syntax error, unexpected '='
@done? = false
^
from /usr/local/rvm/rubies/ruby-1.9.3-p194/bin/irb:16:in `'


[@jakobz]

Бесит "_" у приватных полей в C#.

[@sdevalex]

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

[@edogs]

Не знаю как можно не следовать общему стилю

Очень просто.
Когда проект большой, нужно сделать что-то небольшое, а времени знакомиться со всеми гайдлайнами проекта нет, то… вполне можно ляпнуть getJuneStat вместсо принятого getJunStat, при чем если рядом нет кода в котором написано getJunStat, то Вы просто не заметите, что Вы белая ворона:)

[@hlx]

Вы говорите верно, но иногда встречается код, из-за которого готов бросить программирование :)
А вообще, с книгой, ссылка на которую есть в конце топика, должен ознакомится каждый, особенно начинающий программист.

[@kulinich]

ИМХО С этой книгой обязан познакомиться каждый не начинающий программист. По крайней мере 1 — 2 года опыта программирования должно быть, хотя бы для того, чтобы понимать что в ней написано.

[@VolCh]

Угу, ознакомиться начинающему может быть просто вредно, если он начнёт следовать принципам не понимая зачем.

[@VolCh]

откровенно плохое имя метода чаще всего является главным свидетельством его неудачной реализации

[@arturich]

«obj1, obj2» как говориться — «нет худшей причины назвать переменную $c, чем та, что $a и $b уже заняты»

[@TheHorse]

Ну на самом деле, многие так делают, и все правильно делают. Например, олимпиадное программирование, когда времени очень мало…

[@EuroElessar]

В олимпиадном программировании это не так критично на самом деле :) Много времени за компьютером тратится на обдумывание того — как писать, имена переменных по сравнению с этим тратят очень мало времени.
Ну и не стоит забывать, что IDE вполне сносно автодополняют имена переменных/методов/классов, а ими (IDE) на олимпиадах пользоваться не запрещено.

[@EuroElessar]

И, конечно же, не стоит забывать, что ваш код потом еще, возможно, придется читать сокоманднику, а он точно не обрадуется одно-двухсимвольным названиям переменных, если названия взяты наобум (w для ширины, h для высоты — логично, а вот «a» и «b» для того же — уже сложнее гораздо читать). В таком случае все сэкономленные секунды на написание коротких имен будут многократно съедены тем временем, которое ваш товарищ потратит на понимание кода — а вы ведь в это время, скорее всего, будете писать уже следующую задачу.

[@arturich]

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

А вообще, если вспомнить Дяду Боба, то в книге «Чистый код» он много и дотошно все моменты разбирает и объясняет что и почему.

[@TheHorse]

Не критично, но юзают. А я и не говорил что время именно на кодирование уходит, пишут a, b, c, d… в том числе чтоб и не задумываться над названием. Ну и все-же кодируется так все быстрее, и аутокомплит тому не перечит.

Чтение сокомандником, происходит редко, и при наличии автора, который показывает и рассказывает.

Ну в общем, ваши аргументы, приняты частично). И как факт, таки многие так делают, и иногда все правильно делают.

[@TheHorse]

Ну и помимо олимпиадного, нормальный пример для a, b, c:

procedure swap(var a : integer, var b : integer);
var c : integer;
begin
     c := a;
     a := b;
     b := c;
end;

Что явно лучше чем FirstVariableForSwaping / swapVar1 / tempVar и кучи всего другого.

[@leotsarev]

arg1, arg2, temp

[@TheHorse]

Мне кажется, что это не лучше чем a, b, c.

arg1, arg2 — не информативно, и так понятно что процедура принимает первый аргумент, второй аргумент…

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

С другой стороны, конечно, хорошо всегда писать правильно, по меньшей мере чтоб привычку нарабатывать.

[@VolCh]

С a, b и c могут возникнуть ненужные ассоциации. Например две функции рядом triangle_square(a, b, c) и swap(a, b). Если первая понятна любому, изучавшему геометрию в школе (и английский :) ), то этого же любого вторая может заставить полезть в реализацию. чтобы посмотреть, а что же там со сторонами треугольника происходит, хотя никакого отношения ни к треугльнику, ни геометрии вообще она не имеет. Правда arg1 и arg2 неудачные названия, я бы взял var1 и var2, подчеркнув, что нужно указывать именно переменные, а не произвольные выражения.

[@TheShock]

Есть ещё вариант — назвать «left» и «right» или «first» и «second»

[@TheHorse]

swap — основы основ, название как бы намекает, что там за аргументы).
a, b, c — часто используются в высшей математике, алгебре и прочих весомых науках.

[@VolCh]

Вот и я про то, может возникнуть диссонанс между swap и её аргументами a и b. Вроде swap чисто техническое название, а a и b — научные.

[@TheHorse]

Так хотелось найти пример, но боюсь что boost, .Net, Qt напилили что-то похожее на value1, value2 для таких функций((.

a,b — все-же скорей инженерные, нежели научные. Наука кишит всякими тау, гамма… Впрочем и а, b к сожалению тоже.

Ну ладно, буду делать как все, но аргумент в сторону сильных ассоциаций к a,b — не принимаю). Не верю в существование программистов, которые при виде swap(a, b) подумают про стороны треугольников.

[@Mrrl]

Непонятно. Что такое «треугольный квадрат»? Я такого не только не знаю, но и представить себе не могу. Или имелось в виду TriangleArea?

[@VolCh]

Имелось, но словарь выдал на слово «площадь» перевод «square», а не «area». А представьте от меня ещё требуют комментарии иногда на английском писать :(

[@edogs]

Всё же не все правила абсолютны.

Неизменяемые параметры не должны передаваться по ссылке.
Не используйте входные параметры в качестве рабочих переменных.
Метод должен быть защищен от плохих данных, которые могут нарушить его работу.

Если они большие, то можно и по ссылке. Пару мегабайт данных на фига пихать в функцию «напрямую»?
Если в функции 7 входных параметров, все из которых используются и сама функция небольшая, то переопределение может занять больше места/времени чем использование их как рабочих и привести след. разработчика в задумчивость.
Фактически это обязательно только в публичном методе. Приватный метод вполне имеет право полагаться на проверку этих данных перед ним. Иначе в цепочке вызовов может оказаться такой копипаст проверок, что жуть.

[@sic]

Бывают еще и константные ссылки, которые как раз в большинстве случаев предпочтительны. И тогда их не удастся использовать как рабочие переменные.

[@HotWaterMusic]

Спрашивал месяц назад по этому вопросу того самого Джона Кармака в Твиттере. Он же увлекается всяким таким. Кармак сказал, что по вопросам читабельности кода самое лучшее — вот это.
Ссылок на PDF на английском если что хватает, а лично мне книга понравилась, легко читается легко и сразу есть практическая польза. Code Complete безусловно шире по охвату тем и сравнивать их не стоит, но вдруг кто-то и эту книжку возьмет на вооружение.

[@creage]

Конкретизация методов/функций/переменных нужна только там, где код, с первого прочтения, может быть не очевиден. Не нужно комментировать, что вы делаете, комментируйте почему вы так делаете.

[@edogs]

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

Согласитесь, читать такой код:

Код красивый

function()
{
$a = 1;
$b = 2;
$c = 3;
$sql = '
SELECT
*
FROM
tbl
WHERE
a = 1';
}

Код компактный

function(){
$a = 1;
$b = 2; $c = 3;

$sql = 'SELECT * FROM tbl
WHERE a = 1';
}

Более приятно, чем

Приятно может быть и первый, но хорошим компромиссом для такой ситуации имхо было бы все-таки

Код компромисный

function(){
$a = 1; $b = 2; $c = 3;
$sql = 'SELECT * FROM tbl WHERE a = 1';
}

Потому что первый тип кода приводит к тому, что частенько приходится пролистывать страницы. Код должен быть разумно компактен. Особенно учитывая моду последних лет, когда 4:3 мониторы скукожили до 16:10, а потом и до 16:9… или вообще сумашедшие 21:9 habrahabr.ru/post/145276/

[@DevMan]

Метод не должен быть слишком большим (не более 100)

Не более чего? Строк/экранов/*байт/грамм? :)

[@GrigoryPerepechko]

А разве не очевидно?

[@DevMan]

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

[@GrigoryPerepechko]

Знаете, если человек подумает про 100 экранов или 100 байт, ему лучше не продолжать программировать. Ему даже code complete не поможет. Всё таки у программистов должен быть мозг

[@DevMan]

Да ладно. Вы реально весь такой правильный и никогда не делаете ошибок?

[@GrigoryPerepechko]

При чем тут то делаю я ошибки или нет?
Я просто уверен что большинство тут люди с хорошими мозгами, и однозначно поняли о какой еденице измерения шла речь.
Метод размером 100 строк. Очевидно же.

Какие к черту байты, экраны? Зачем вы бред несете? Вам приятно ощущать себя дурачком?

Это серьёзный IT ресурс а не ясельная группа. Да, хабр сгавнивается с годами, все меньше серьёзных постов, но ведь это не повод устраивать смешнявочки из за недописок. Если вы нашли однозначную ошибку в статье — ну писните автору в ЛС. Зачем разводить детский сад?

[@TheHorse]

Инженерия и наука требуют точных высказываний, которые не дают шанса термину «неоднозначность».

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

Не принимайте близко к сердцу, практика показывает что в таких ситуациях дешевле будет сказать «Прошу прощения, поправил.»

[@DevMan]

Про очевидность я вам ответил выше.
Для вас очевидно (должно быть у вас есть мозг). Для меня очевидно (знаком с software metrics). A для кого-то начинающего может быть очевидно, что метод должен содержать не более 100 операций.

В итоге, не нравится мой комментарий — есть минус для него, есть минус в карму.
Выпустите пар на них и продолжайте читать сей серьёзный IT ресурс, вместо рассуждений на тему мозга у программистов.

[@resurection]

Конечно все догодались, но для этого пришлось напрячь мозг на 0.5 секунд. Ирония в том, что это в статье про перфикционизм и про прекрасно офрмленный, легко-читабельный код. Если бы эта надпись была в любой другой статье — никто бы и не обратил внимание.

[@resurection]

Тут тоже всё очевидно:

function(){
  $a = 1;
$b = 2; $c = 3; $sql = 'SELECT * FROM tbl
WHERE a = 1'; return $this->my_sql->q($sql);
}

Что тут не очевидного?

[@DevMan]

Все очевидно. Только за такое форматирование кода хочется человека как минимум обозвать. Как минимум — редиской.

[@resurection]

"(не более 100)" — за это тоже.

[@hlx]

за троллинг — тоже. Я же исправил.

[@TheHorse]

Мне что-то не очевидно зачем там $a, $b, $c. И что такое метод q?

[@TheHorse]

И как потом вызвать эту функцию? О чем пример?

[@hlx]

Спасибо, исправил

[@f0b0s]

Очень напоминает пересказ одной из глав «Совершенного кода»

[@f0b0s]

Ах, автор об этом упомянул. Я воспользовался правилом «The Wadsworth Constant» и сразу начал читать со второй трети статьи.

[@anitspam]

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

[@hlx]

оформление SQL кода, с новой строки (как у меня), или придерживаюсь всех отступов — как у вас, уже пожеланию. Главное что бы был читаем SQL (beautiful query). Различия незначительны, лишь в количестве действий при наборе — у вас отступов больше :)

а по поводу скобок и пустых строк — это, как описано в топике — строго по гайдлайнам компании.

[@alekciy]

Ничуть не слишком. Это удобно читать и камитить. Пример:

$sql = '
	SELECT
		  i.e_id
		, iv.iv_id		AS id
		, iv.value
		, iv.ep_id		AS element_property_id
	FROM
		' . $this->schema . '.item AS i
	LEFT JOIN
		' . $this->schema . '.item_value AS iv USING (i_id)
	WHERE
		i.i_id = '. $this->db->getSqlInt($item['id']) . '
';

Весь «скелет» запроса виден по SELECT...FROM...LEFT JOIN...WHERE. Из какой таблицы выборка, что выбираем, с чем джоиним, по каким условиям. Запятые в начале для камитов. Если завтра потребуется добавить новое поле, то в дифе мы увидим ", iv.new", т.е. затронута будет одна строка, а не две как в случае если поля разделять запятыми в конце строки.

[@VolCh]

LEFT JOIN я бы сдвинул ещё, всё таки он относится к FROM, а не является самостоятельным элементом SELECT.

А вообще, когда выражение простое вроде «SELECT * FROM table», то при виде его разбитым на 4 строки возникает неоднозначная реакция.

[@alekciy]

В JOIN, как и в FROM, находится имя таблицы, поэтому он вровень с FROM. Ведь по сути, работаем мы уже не с таблицей указанной во FROM, а таблицей полученной объединением. Поэтому в SELECT у нас имена полей, а в FROM...JOIN таблица.

Какой бы простой код не использовался, он должен соответствовать стилю кодирования. Это сильно облегчает чтение кода, а бОльшую часть времени на живом проекте мы все же читаем, а не пишем код. Разбиение на несколько строк очень полезно оказывается для дифов. При однострочной записи изменение любой чисти запроса приводит к включению в диф камита всего запроса, разделенный же на строки запрос в дифе дает только измененные строки. Крайне полезно при командной разработке, особенно при отслеживании камитов других разработчиков. Но и работая в одиночку подход показывает себя очень удобным. Читаемость должна находится на первом месте. Многословность форматирования легко может фикситься через минификацию/обфускацию на этапе сборке проекта. В контексте php это сборка в phar файл(ы).

[@VolCh]

Ну я сматриваю (а иногда и пишу) FROM… JOIN… ON… как FROM (… JOIN… ON ...), то есть имея ввиду как раз, что «аргументом» FROM является как раз «виртуальная» таблица, а состоит она из одной или объединения двух или более — не суть. Ваш вариант мне напоминает запись типа

$var
=
  2
+
  2

а я предпочитаю

$var
  =
    2
    +
    2

[@alekciy]

Ну тут уж кому как удобно/какой стиль кодирования принят в проекте. Я лично за первый, т.к. идет разделение на уровне форматирования на оператор, идущий без отбивки, и его операнды, идущие с отбивкой слева. В твоем же случае два оператора, = и +, отбиты по разному. Хотя логика понятна «сложение 'внутри' присвоения».

[@VolCh]

>Читаемость должна находится на первом месте.

Согласен, вот только представления о ней у каждого свои :)

>Многословность форматирования легко может фикситься через минификацию/обфускацию на этапе сборке проекта. В контексте php это сборка в phar файл(ы).

Обычно это не нуждается в фиксе. А сборка php-проекта, по-моему, очень редкий зверь. Я так его наблюдал только когда пробовал HAML прикрутить к PHP из спортивного интереса.

[@alekciy]

Редкий, просто потому что народ на это тупо забивает/не думает. Это как быдлокодинг. Но сбор проекта в один файл дает неплохой прирост. Поэтому я лично считаю этот аспект на столько важным, что хочу включить сборку в единый phar файл в своем проекте.

[@VolCh]

Информации о плюсах мало, а привычные сценарии разработки, разворачивания, обновления и поддержки (читай — правка кода на сервере :) ) ломает.

А вообще я больше не о phar (тут-то понятно, без сборки никуда), а вещах вроде «инлайна» инклудов, минимизации html, css и js, то есть препроцессинге и компиляции не в рантайме.

[@Shedal]

А зачем у вас перед FROM отступ? По логике ведь, эта строка не менее (а то и более) первостепенна, чем INNER JOIN.

[@Shedal]

Кстати, я в WHERE отступы делаю по той же самой логике, вот так:

SELECT *
FROM tbl
INNER JOIN tratata
  ON zozo.zozo = zaza
WHERE a = 1
  AND z = 1000

В случае с AND условия получаются ещё и выстроены на одном уровне.

[@lesha_firs]

А я так пишу, удобней комментировать условия для отладки.

SELECT
tb1.*,
tb2.*
FROM
tb1
left join tb2 on tb1.id = tb2.id
WHERE
tb1.`date` = '2012-06-15' and
tb2.`date` = '2012-06-15' and
tb1.cat = 1

[@vitalets]

Я в последнее время после where всегда единицу ставлю, так удобней если какое-то условие закомментить нужно:

SELECT *
FROM tbl
INNER JOIN tratata
  ON zozo.zozo = zaza
WHERE 1
  AND a = 1
  AND z = 1000

[@ferasinka]

В аду есть специальный котел для тех, кто пишет открывающую фигурную скобку на новой строке :-)

[@hlx]

Хм, если честно, я сам всегда писал открывающую фигурную скобку на той же строке, где и сама функция, но сейчас я ограничен стандартами компании :)

[@Shedal]

… и он пустует, потому что такие люди в ад не попадают? :)
Если серьёзно, то вот это уж точно является делом привычки. А также, традиций. В Java принято ставить открывающую фигурную скобку на той же строке, в C# — переносить.

[@lesha_firs]

Насколько я помню ядро люнекса написано на таких скобках. Давным дано еще когда не было нормальных иде. так было удобней смотреть где открывается функция или условие и где заканчивается. Вот оттуда и понеслось.

[@VolCh]

Соблюдение стандартов кодирования важнее субъективного мнения о них. Главное чтобы в одном контексте было одинаково, например для классов и методов на новой строке ставить, а для if, for и т. п. в той же.

[@frenzytechnix]

Есть как минимум три соглашения о расстановке фигурных скобок в коде:

BSD style:
if(x == y)
{
  something();
}

GNU style:
if (x == y)
  {
    something ();
  }

K&R style:
if (x == y) {
  something();
}

Какой из них использовать — зависит от соглашений, принятых в компании либо заданных самим языком.
К примеру, в Perl согласно Perl Best Practices рекомендуется использовать K&R style.

[@VolCh]

Не редкость и комбинация, когда для одних конструкций (функций, классов, методов например) используется один (BSD), а для других (управление потоком) — другой (K&R).

[@orionll]

В аду есть специальный котел для тех, кто разводит такие холивары.

Мое мнение — главное, чтобы везде было одинаково. И пох, с новой строки, или на той же строке.

[@Anexroid]

А не хватит ли уже на Хабре писать однотипные статьи по оформлению кода?

Никакой новой инфы, которой не было в over 9000 таких же статей на тему «Как именовать переменные, методы и ставить отступы»

[@mrjj]

ага, читаешь интернет — и действительно, зачем столько однотипных статей, читаешь чужой код и понимаешь, что таких статей слишком мало, а каждому второму разработчику нужно стучать МакКоннелом по голове, чтобы не писал щуйни вроде
uuU_NEW+=uuUold-uuOLD

[@Mezomish]

Вы подождите, еще про табы/пробелы никто не заикался…
OH SHI~…

[@IkaR49]

Согласитесь, читать такой код:
…
Более приятно, чем
…

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

P.S. Интересно, кстати, что раньше подобного за собой не замечал и сам всё всегда расписывал построчно.

[@hlx]

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

[@tagir_valeev]

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

Странное правило. Вы предлагаете, чтобы сигнатура метода была завязана на его реализацию? А как же инкапсуляция? А если метод переопределяется, и в переопределённом методе порядок другой?

Вообще публичные методы должны быть определены в интерфейсах, где «использование внутри метода» вообще не предполагается, а порядок параметров в непубличных не так важен.

[@step307]

К названиям методов, возвращающих boolean, полезно применять тоже правило что к boolean переменным. А именно:

file->checkViruses()

vs.

file->isVirusFree()
или
file->hasVirus()

[@vitalets]

Имена булевых переменных должны быть в утвердительной форме и подразумевать булево значение: done, error, found, finished. Плохо: status, source.

можно еще добавлять is: isDone, isError, isFound

[@orionll]

Is иногда грамматически не подходит. К примеру, document.hasErrors, objects.areEqual, page.willBeRemoved

[@myadzel]

Один из лучших комментариев, что я видел за последнее время.

[@mrjj]

Можно было бы ограничиться последний ссылкой.

[@Lure_of_Chaos]

Ребята (и автор) — это, конечно, все очень хорошо, копья ломаны не раз.
Хотел бы заметить совсем другое: нужно при оформлении кода ориентироваться на читающих, а не на всех.
То есть, если это мой единоличный проект, то его код, скорей всего не будут читать (зачем? рынок и без того перенасыщен приложениями и библиотеками), поэтому, имхо, глупо его красиво оформлять. Он должен удовлетворять лично мои потребности.
Если я пишу в команде, то неважно какой там кодстайл используется, важно, чтобы он был и был один. Читать его будет только команда. Новички скорее привыкнут к не очень им нравящемуся стилю, не нужно угождать им.
Если проект с открытыми исходными кодами… Думаю, аналогично. Конечно, потенциально его будут читать больше «левых» людей, но это как бы уже их проблемы.

Т.е. «я не 10$, чтобы всем нравиться» и «овчинка выделки не стоит».

[@Alex_At_Net]

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

[@Gluttton]

Вот только на практике проще добиться абсолютной точности чем примерной (это и про кирпичи и про программирование).

[@Derailed]

Добавлю от себя немножко:

1. Старайтесь избегать условных компиляций, да исключением #indef в заголовках. Если же угораздило вляпаться в мешанину #if, #ifdef, #else и т. п., то старайтесь делать условные блоки как можно короче, оформляйте операторы условной компиляции отступами и (желательно) подробными комментариями.

2. Не используйте табуляцию для оформления кода, заменяйте её пробелами. Если же используете табуляцию, то добейтесь, чтобы у всех участников проекта (сотрудников компании) настройки табуляции одинаковые (у всех должно быть задано использование табуляции с одинаковыми параметрами).

3. Вместо реального кода используйте как можно чаще константы, вычисляемые во время компиляции.

4. Для бекапа и обмена кодом используйте систему управления версиями (SVN, Git, Merqurial).

5. Уделяйте время для ведения сопроводительного дневника проекта — простого текстового файла, где делайте наброски алгоритмов, кратко записывайте, какие изменения были сделаны, описание проблем, замечания по оставшейся работе (todo).

[@DevMan]

Не используйте табуляцию для оформления кода, заменяйте её пробелами.

Абсолютная ересь.
Есть code convention, им определяется все.

[@Lure_of_Chaos]

Табуляция объективно хуже тем, что не имеет постоянной ширины. В результате код, красиво выровненный с табами = 4 пробела, превращается в дикую лесенку при табах = 2 пробела.

Если нет иных code conventions, использую 2 пробела. Опыт показывает, что это идеал.

[@DevMan]

Табуляция объективно хуже

Что русскому здорово, то немцу смерть.
Ваше суждение субъективно. Срача на тему «tab vs space» здесь было достаточно, не хочется устраивать очередной.
Используйте, что угодно, только не возводите это в разряд абсолютной истины.

[@green_fr]

Переходя к практике: может кто-нибудь посоветовать настраиваемую утилиту форматирования кода? Потому что всё описанное (в части оформления кода) — это хорошо, но когда стандартные IDE не помогают вообще, сложно разношерстную команду подбить под одни правила. Или там, унаследовав от предыдущей команды сотню классов в произвольном форматировании, не хочется терять часы на форматирование ручками.
P.S. У меня конкретно MatLab, но я готов потратить время на конфигурацию готового продукта. Писать с нуля парсер не готов.

[@Ryadovoy]

Наши соглашения о кодировании включают рекомендации из книги Герба Саттера и Андрея Александреску:
Стандарты программирования на C++. 101 правило и рекомендация.

[@Ryadovoy]

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

К примеру такое объявление переменных у нас запрещено, т.к. приводит к ошибкам:

int someCounter, someOtherValue = 0;

или условные операторы без скобок также запрещены, т.к. можно дописать что-то, а скобки забыть:

if (someValue == 0)
    WriteTrace("Before do something"); // эта строчка была добавлена позже
    DoSomething(); // ошибка, этот код будет вызываться даже если someValue != 0

Но снижение ошибок не должно быть важнее удобочитаемости, и по этому мы не следуем рекомендации писать константы перед переменными в сравнениях:

if (ERROR_SUCCESS != GetLastError()) // IMHO, снижает читабельность кода

[@Ryadovoy]

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

int *somePointer, *anotherPointer;

Но так, как у нас однострочное объявление запрещено, то мы спокойно пишем так, как нам удобно:

int* somePointer;
int* anotherPointer;

[@Ryadovoy]

Спорные моменты по форматированию, такие как на какой строчке ставить скобку, либо где ставить пробелы, у нас принимались простым голосованием, т.к. нет четких доводов ни за ни против какого-либо варианта. В конечном итоге это не так ужи и важно, главное чтобы был один стиль в рамках проекта.

[@Ryadovoy]

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