Исключительная красота исходного кода Doom 3

Я видел код, который перегружает оператор '%' чтобы обозначить продукт с точкой

это dot product что ли? вашу ж мать, переводчики…

Второй закон кододинамики: энтропия кода не убывает.

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

Сложилось впечатление, что автор назовет прекрасным любой код, обработанный code beautifier'ом с нужными настройками :)

Интересно было почитать, спасибо за перевод!
Вообще, при чтении таких статей нужно понимать, что многие вещи субъективны и являются делом вкуса.
Например, расстановка фигурных скобок в таком виде:

if(smth) {
    doSmth();
} else if(smthElse) {
    doSmthElse();
}

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

if(smth)
{
    doSmth();
}
else if(smthElse)
{
    doSmthElse();
}

Читать гораздо приятнее. Исключительно ИМХО.

По поводу написания комментариев в коде и вынесения всего, что только можно, в отдельные функции — если сранивать с более длинными функциями, разделёнными на «подсекции» при помощи комментариев-подзаголовков, то это просто-напросто два разных подхода к организации кода. Мы к такому выводу пришли в нашей команде после пары недель ожесточённых споров :)

Статья — красота! Спасибо!

Как-то поверхностно выглядит статья, например абзац про комментарии.
С большинством дифирамбов мне как-то трудно согласиться. Например, с хвалой форматированию кода. Мне кажется, что это вкусовщина. Меня, например раздражают открывающие скобки в той же строке или несколько выражений, записанных в одной строке. Но мне не лень нажать две кнопки в IDE и привести форматирование любого исходника к удобному для меня виду.
На мой взгляд, трюки, вроде ...split(..., const float epsilon, ...) только снижаю читабельность, потому как, подсознание нашептывает, что epsilog передается по ссылке, но не модифицируется, ан нет.

А вообще, зачем это const float? Как будто float может измениться, странно смущает меня это почему-то.
Про выравнивание. Есть два понятия: indentation и alignment, вот для первого табы — самое оно, а второе делать табами — сомнительно, потому, что кто-то может не любит табы в 4 пробела, сделает в 2, и все поедет к черту.

финальный модификатор const после списка параметров — мой самый любимый. Он указывает на то, что idSurface::Split() не будет изменен самой поверхностью (surface).

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

За последние 6 недель разработки Dyad я дописал 13k строк кода.

Вот это скорость! При стандартном 8-часовом рабочем дне получается примерно 1 строчка кода в минуту.
Видимо, проект так нравился автору, что он его и дома не оставлял ;)

> Он указывает на то, что idSurface::Split() не будет изменен самой поверхностью (surface).

Ээ, чего? Функция изменяется поверхностью?
Может, наоборот, а?

Любопытно, почему это геттеры-сеттеры лишние. Понадобится ввести валидацию входных данных — это будет намного проще ввести с сеттером, чем лазить по всему коду и ставить проверки где нужно. Я лично стараюсь вводить геттеры-сеттеры даже тогда, когда уверен что эта переменная может быть свободно модифицирована и считана.

Всегда думал что функции типа serVar(..) и getVar() создаются только если надо контролировать значение.
Например чтобы переменная никогда не была равна нулю.
Поэтому думаю что не всегда следует использовать переменную в public.

Некоторые моменты весьма спорны. Вот с const и с выравниванием табуляцией имен методов и переменных согласен.

довольно забавно, автор предлагает сделать все переменные константными, но при этом восхищается «открытыми» полями в классе. вообще мне кажется только в С++ какой-то особый культ поклонения const :)

Возможно, я еще пожалею об этом, но напишу:

Я ненавижу else и else if в условиях, и пишу «ленивые» функции и циклы.
Ленивые — потому, что они хотят как можно быстрее завершиться.

оригинал
int check_param_and_do_someting(int param)
{
	if( param > 0 )
	{
		if( param % 3 == 0 )
		{
			//do something
			return 0;
		}else
		{
			return -2;
		}
	}else
	{
		return -1;
	}
}


"ленивый" вариант:
int check_param_and_do_someting(int param)
{ 
	if( param <= 0 )
	{
		return -1;
	}

	if( param % 3 != 0 )
	{
		return -2;
	} 
	
	//do something 
	return 0;	
}

В этом случае нет многоступенчатой вложенности

В циклах — тоже самое. Сперва проверяются условия для break или continue, а потом идет сам код цикла.

Кажется, этому стилю есть какое-то название, но я его не смог выгуглить — придумал «ленивое».

Автор мог бы просто прочесть code convention ftp.idsoftware.com/idstuff/doom3/source/CodeStyleConventions.doc
вместо того, что бы пытаться восстановить его по исходникам

В Doom 3 действительно очень хороший код, это уже ни раз обсуждалось. Как с точки зрения выбранного стиля, так и архитектурно.
Но большая часть того, что описывает автор в статье — результат жесткого придерживания корпоративному стилю, что и породило однообразие и удобочитаемость. Я могу привести другой пример отличного исходного кода, но с другим, во многом противоположным, соглашением — Ogre3D. Его читабельность не хуже, а как по мне — даже лучше.

В статье Кармак не зря упоминает«Эффективное использование C++» Скотта Майерса — настоятельно рекомендую к прочтению. Отпадут простые вопросы «зачем везде нужен const?», возможно, научитесь писать безопасные относительно исключений функции и многое другое.

Если пробежаться по пунктам статьи, я могу сказать следующее:
1) Мало комментариев — плохо. Много комментариев — тоже плохо.
Их должно быть ровно столько, чтобы убрать любые неоднозначности. Так же я за достаточно подробные комментарии в объявлении функции (тут, видимо, сказывается общая приверженность к инструменту для генерации документации — Doxygen).
Например, прочитав это объявление, даже незнакомый с остальной частью кода программист, сразу все поймет:

        /** Find all file or directory names matching a given pattern
            in this archive.
        @note
            This method only returns filenames, you can also retrieve other
            information using findFileInfo.
        @param pattern The pattern to search for; wildcards (*) are allowed
        @param recursive Whether all paths of the archive are searched (if the 
            archive has a concept of that)
        @param dirs Set to true if you want the directories to be listed
            instead of files
        @return A list of filenames matching the criteria, all are fully qualified
        */
        virtual StringVectorPtr find(const String& pattern, bool recursive = true,
            bool dirs = false) = 0;

2) Отступы — дело привычки, ровно как и расположение открывающейся скобки. Тут даже странно говорить про удобство, профессионализм или что-то еще. Как я уже писал выше, у нас половина разработчиков работают на Full HD мониторах в вертикальной ориентации — все всегда помещается.

3) Отказ от шаблонов в основном API — скорее правильный выбор, нежели нет. В конце-концов, хорошо оперируют шаблонами достаточно малое количество программистов.
Но на низком уровне убирать шаблоны — странное решение. То, что привел в пример автор, смотрится как минимум странно. Вполне возможно, у него какое-то странное представление о шаблонах.
А boost сложен в чтении обычно потому, что он предельно универсален. Они ведь не знают, что будут писать конечные пользователи библиотеки, в отличие от ребят из id, которые четко знали, зачем и для чего они переписывают STL.

4) Использование get/set в именах функции — опять же удобство для программиста.
Например, используя автодополнения кода в своей IDE, я, даже не сильно зная API, могу просто написать get и получить полный список всех доступных мне функции, возвращаемых данным классом. Аналогично с set.
Использование же функции, возвращающих значение без префикса get, иногда просто приводит к неоднозначности.
Например:

void renderSystem(RenderSystem* system);

Что значит этот код? Мы инициализируем систему рендера? Или мы просто устанавливаем систему рендера, но ничего с ней не делаем? А может мы ее добавляем в какой-то список доступных систем рендера? Неоднозначно.
Другое дело:

void setRenderSystem(RenderSystem* system);

Тут все яснее — мы устанавливаем систему рендера. Инициализации или что-то там еще в этой функции проходить не должны.

5) stringstream
Лучше всего использовать boost::format. Это и безопасно, и понятно. Рекомендовать вместо stringstrean использовать printf — очень, очень странно. printf небезопасен, в местах его использования очень часто вылезают ошибки (о чем, кстати, написано в статье). Я не стал бы слушать человека, который рекомендуют использовать printf, когда рядом есть огромное число куда более хороший инструментов.

10) Собственно, не использовать перезагрузку операторов — тоже весьма странный совет. Перезагрузка operator() и operator= — это вообще фундамент C++.

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

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

Я мечтаю о том, чтобы все переменные в C++ по умолчанию были const

Как-раз один из пунктов, за которые я люблю Rust.

В целом отношение к const как автора статьи, так и Кармака, очень радует. Фактически, это показатель доли функционального стиля в их программировании. Противники такого подхода могут заметить, что для этого нужно писать много буков — и будут совершенно правы. Поэтому внимание пора обратить более подходящие инструменты, где функциональный стиль смотрится компактно и естественно (Scala,Rust).