Рекомендуемые правила оформления кода

[Вадим Мошев]

Кое-что по оформлению хочу сказать.

В настоящее время на своей работе пишу программу (программа до жути простая, хотя уделяю ей мало внимания, посему работаю над ней уже довольно долго).

У меня изменились видения оформление кода. Итак, что могу сказать.

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

Конечно, с одной стороны гигантские отступы хороши тем, что иерархия кода прослеживается довольно чётко:

for i:=1 to N do
		for j:=i to M do
				for k:=1 to S do
						// а вот тут тело

Однако, бывает и так, что выше указанная конструкция может быть телом какого-либо другого оператора, и в этом случае "ширина" кода становится не очень приемлемой, особенно это ОЧЕНЬ неудобно, когда проводится пошаговая трассировка. При очередном нажатии клавиши F7 (в Dephi 7 пошаговая трассировка выполняется этой клавишей), окно редактора делает горизонтальную прокрутку влево до упора, после чего я наблюдал пустое окно, и для того чтобы вновь прочесть его, мне необходимо было крутить вправо (хотя это, может, зависит от IDE, возможно, в других нет такого, но в выше обозначенной такое есть, хотя, это, может быть, отключается в настройках, не знаю)

Теперь же "щедрость" на отступы у меня немного утихла, и теперь, чтобы код был "поуже", я бы написал это следующим образом:

for i:=1 to N do
	for j:=i to M do
		for k:=1 to S do
			// а вот тут тело

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

Следующее изменение коснулось объявления переменных. Скажу сразу: для кого-то это покажется не_новым.
Это изменение состоит в том, что каждая переменная объявляется с новой строчки (за исключением лишь некоторых, смысл которых очень прост, например параметры циклов), справа от объявления (от описания, скорей) ставится комментарий, поясняющий назначение переменной.

var
	SortedArraysCount: Word; // Счётчки отсортированных массивов
	i, j, k: word; // Просто параметры циклов, наверное
					// можно было вообще не комментировать
	
	IsMatrixSingular: boolean; // флаг показывающий сингулярность матрицы
	IsStackEpty: boolean; // Флаг, показывающий пустоту стека
	
	ProcessFailFilesCount: word; // количество файлов, обрабокта которых
									// завершилась ошибкой

У меня такой способ сформировался благодаря написанию кода в стиле "вниз-вверх-вниз", когда нарушается порядок написания кода сверху-вниз и слева-направо. В частности бывает так, что перед тем, как продолжить написание кода, приходится объявить одну/несколько переменных. Поэтому здесь можно заметить, что переменные одного типа (например, boolean) объявлены в разных строках.
Ещё особенности:
Если комментарий длинный, его, как ни странно, целесообразно разбить на две части, при этом вторую часть комментария следует писать приблизительно с той же позиции, что начало этого комментария, или, возможно, немного правее. Во втором случае (на мой взгляд) будет чётче видна иерархия комментария, то есть, вторая часть - это не новый комменарий, а продолжение первого.

Несколько слов о наименовании переменных (возможно, кое о чём я уже говорил ранее).
1. Если имя переменной логически состоит из нескольких слов, то каждое новое слово начинается с большой буквы (всё остальные маленькие, символ "_" как-то у меня не прижился).
2. Переменные следует именовать так, чтобы, разделив её на составные слова, получилось бы правильно построеннео с точки зрения английского языка предложение (IsStackEmpty -> Is Stack Empty = Пуст ли стэк?). Здесь правда неудобство связано с тем, что уровень английского языка у всех разный, хотя программисты должны владеть им хорошо.
3. (об этом ранее не писал). Некоторые названия переменных снабжаются специальными суффиксами/постфиксами, показывающими смысл этой переменной.
В частности, у меня (возможно ещё не до конца устоялся у меня этот пункт) флаги начинаются словом "Is", а счётчики заканчиваются словом "Count".
Возможно, такая технология наименования и существует, у меня она выработалась сама. Знаю, есть нечто похожее, называется "Венгерская нотация", но это немного не то.

[Вадим Мошев]

Ещё кое-что про условные операторы.

Я уже раньше о них писал, хотелось бы уточнить кое-что.

Если в теле (ветке) условного оператора содержится лишь один оператор, то:
Слово Then/else вместо со своим оператором переносится на другую строку.

if Condition
	then Operation;

Если же в теле (ветке) условного оператора содержится несколько операторов, то
1. Слова Then/Else переносят на новую строчку и остаются единственными, то есть, кроме них на этой строчки ничего быть не должно.
2. Ниже (на следующих строках) записывается последовательность инструкций.

// например, так, один из вариантов
if Condition
	then Operation1
	
	else
		begin
			Operation2;
			Operation3;
			//...
		end;

Кстати, напомню, что операции записываются не вровень со словами begin/end, а немного правее.

я отредактировал это сообщение, изменит тэг quote на code

[psycho-coder]

Вадим, вы прямо целю документацию по оформлению кода составили) Может каждому и участников написать инструкцию по оформлению кода, как он это видит, и в блог? А там пусть читают, выбирают какая понравится?

[Вадим Мошев]

Сообщение от psycho-coder

Вадим, вы прямо целю документацию по оформлению кода составили) Может каждому и участников написать инструкцию по оформлению кода, как он это видит, и в блог? А там пусть читают, выбирают какая понравится?

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

[Sna1L]

Топик, вейк ап!

Модераторы, может быть, стоит её закрепить?

[crazy horse]

http://www.possibility.com/Cpp/CppCodingStandard.html
http://www.gnu-pascal.de/h-gpcs-en.html#Formatting
http://sourceforge.net/adobe/flexsdk...20Conventions/
http://www.oracle.com/technetwork/ja...oc-136057.html
Мне еще поискать международные соглашения, или вы и дальше будете огород городить? А потом еще ругаются, что чужой код читать невозможно. Ежу же понятно, что невозможно, проще свои правила выдумать, чем пару страниц на английском прочитать.

первое больше напоминает сборник правил, которые нравились автору.

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

Модераторы, может быть, стоит её закрепить?

Знания надо закреплять и мозги, а не такие темы, которым место в печи.

А там пусть читают, выбирают какая понравится?

Залить бетоном! Пока не ожило.

[Пепел Феникса]

первое больше напоминает сборник правил, которые нравились автору.

[Вадим Мошев]

crazy horse
Как-то вы резко написали свой пост.

А потом еще ругаются, что чужой код читать невозможно.

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

А здесь (ИМХО) приведены примеры неплохо читабельного кода.

[crazy horse]

Мне даже уже спорить не хочется. Поймете, примете - хорошо. Нет - ваши трудности (и ваших коллег.) Мне с вами вряд-ли придется встретиться в профессиональной области, поэтому вы правы, я излишне резок. Продолжайте в том же духе Тем ценнее те специалисты, которые не изобретают велосипеды в оформлении и не брезгуют стандартами. Тем более, от безбожной структуры кода у меня давно есть иммунитет: Alt+Ctrl+l Благо инноваторы редко джитом пользуются, мержить все это после реформата не приходится.

Джитом они ваще не пользуются, потому как правильно произносится гит.

Согласен, но отношения к теме не имеет.

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

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

[still_alive]

http://www.possibility.com/Cpp/CppCodingStandard.html

Ну собствно как всегда: много хорошего в сочетание со спорным. Поэтому кому надо, тот для себя (компании) допилит. И в идеале урежет по максимуму.

Тем ценнее те специалисты, которые не изобретают велосипеды в оформлении и не брезгуют стандартами.

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

Благо инноваторы редко джитом пользуются, мержить все это после реформата не приходится.

Джитом они ваще не пользуются, потому как правильно произносится гит.