The Beauty Of Doom 3 Source Code 

"Sometimes, the elegant implementation is just a function. Not a method. Not a class. Not a framework. Just a function." -- John Carmack

People who dont like comments havent had to deal with 30yr old code that was done by a guy whos been dead for 12years.

Just wait until you need to port a Japanese game from the 90s to present day consoles… you will absolutely love comments.

@16:00 I think a little vertical whitespace can be considered a form of self-documenting code, as it can help group statements in a function together based on their purpose and demarcate these ideas from others.

Having worked in SW for many years, for me what defines a beautiful code base is very simple: When somebody gives you an initial ticket to add some functionality, as usually happens when you 1st join a team, without knowing the code base, it should be super simple to track down where code needs to be added, look at the surrounding code, and figure out how to augment it to do what you need. If that can all be done in a short time frame, than IMO the code is beautiful. And that's all there is to it, IMO. Code needs to be maintained & built upon, it's as simple as that. So as long as it's easily approachable and readable? It's good.

"Code should be self-documenting" is a very funny point. I had an interview once at a consultancy where one part of their technical interview was some kind of code analysis. They gave me a short piece of code where they said to assume it runs fine and has no errors. The task was to somehow make it better. They left the room and gave me some time to think. My simple answer when they got back was "more self-explanatory function and variable names", which they sort of accepted, I think, but they mainly wanted comments in there. Worst technical interview I've ever had. I kinda failed that one, and had another one at the same company where we spent an hour talking about a developer roadmap. (Should probably say the code wasn't that complex, getting an item from an array and some other functions) Had two other technical interviews at two other places that were both sort of a pair programming session to write some unit and integration tests. Those were much better

That “unlock a problem solving way” is the fondest memory of my dad an I when he showed me away to solve this Hanoi Towers puzzle in 4 or 5 lines of code. Teaching me 15 year old me about recursion. And after he showed that magic told me to avoid using recursion whenever you can or are 100% sure it can’t cause a stack overflow.

I am not a rust dev, nor am I using htmx, but I totally felt soulbros with Prime when he pulled out his "Devtools" and started removing annoying html blocks from the page he reads. I do that with ublock. I also separate code blocks with empty lines, it is like commas to me: you can read without them, but it is nicer.

I love this commentary for four reasons: 1. Operator overloading. I hate it someone made a a bit shift into a string concatenation.. 2. I spent to many hours debugging ATL/STL in the late 90s/early 2000s. That was incredibly frustrating. 3. API design. Focus on clarity, not cleverness. I appreciate you highlighted that. 4. I have my copy of effective c++ right behind me. Thanks for that reference.

16:00 I definitely prefer spacing in blocks. I find it infinitely easier to read (even when I wrote it myself) when there are separations. And as far as I remember doom3 source does it. I only surfed it a couple of times, but I've worked a lot with Quake 2 and Quake 3 source code and they definitely leave space in those. Also, it should be noted that Doom3 was iD's first project using C++. They used C for all their previous projects, so Doom3 is C++ with a heavy influence of their C habits. (I suspect they only moved to C++ because the people who used to license the engine were requesting it to be C++)

Regarding "one function should do exactly one thing" I think that it is more important to avoid doing things like mutating and persisting in one function than it is to limit to one thing, because "one thing" is highly subjective.

On input and output, I miss Ada's solution for this. You can declare a function parameter as `IN` `OUT` or `IN OUT`

If you checkout Carmack's contribution to the Meta Quest codebase re: VR motion controller, you'll see lots of highly detailed ASCII art schematics showing the system and then a bunch of beautifully self-documented stuff.

The reason a lot of people don't like having curly braces on the same line is so you easily tell which curly brace relates to which other curly brace quicker. In a lot of IDE's you highlight one and it highlights the other. When are in the same horizontal position it jumps out much quicker.

"If your code definition takes more space than body, you probably left the path of good programming" TypeScript: 👀👀👀

16:30 I like having each function be a discreet paragraph so in vim I can just 'dap' to cut the whole thing or 'vap' to select the whole thing, and then if I'm working in a repl I hit my send to repl button.. Makes it nice.

I used to work at a game dev company that wrote in C++ and their codebase was not beautiful let me tell you. There was 3 different sets of string handling paradigms that had to be used in different places in the code, Thats right, they had stringhash, stringview, and stringviewhash in 2 or 3 different forms each. It was insane because they weren't even all mutually compatible with eachother.

as someone who is still learning the ins and outs of C and other code stuff i think Commenting is great. Helps me personally have my stars above moment when i had no idea what i was writing when i was writing it.

The no brackets for single statement inside for loop or if can also cause bug if you interpret its scope incorrectly, since then I decided to always add brackets.

telecommunications is the hardest "medium" to program in. actually it's typically regarded as the most difficult, highest failure rate and highest expert level (meaning need longer time to establish seniority) than any other field.. in human history. i kid you not those people are doing the hardest engineering in the world only for a rogue cosmic ray to flip a bit in their L5 switch and yet somehow companies like cisco are able to maintain 99% uptime for everyone. it is a massive feat that no one notices.

Re: beauty is a function of understanding, to me a defining quality of beautiful code is that as your understanding increases, it makes you like the code more. Bad code, you look at thing, and you might look "that's fine", but later you realize "wait wait WHAT?!" as you understand the horrors going on. Or, you might keep being "meh". But beautiful code, you learn more, you like it more.

logical code blocks gang. Love to bunch things together that are related and then leave a space before the next thing.

This is the first video where Flip's editing has been clear and noticably good

I had hoped this video to be an original look through of the Doom 3 source code it is a 40 minute ramble about someone's blog post.

honestly watching Prime's content in general, but especially this video is making me realize that UnrealEngines 'version' of c++ isn't any different than regular old c++, they've just sort of handled a lot of what can be considered good c++ practices like the ones mentioned in this.

16:00 I personally like it in chunks not one chunk. I can't read the code well if its just one blob of text/characters, if I need to scroll, I'll scroll, it personally amazes me people make it look like its a chore. But each to their own, ultimately it's about who is maintaining the code base, and does it work for everyone who is.

6:57 May we know - where did you get this from? In JS you can also make in/out parameters, only out parameters cannot be primitive types because of language peculiarities (they are passed as copies of values, there is no way to create a pointer), but otherwise the principle is the same.

Wow never would I have thought that they were parallelizing workload this early into their engine since by this time a lot of developers were only using one CPU core to handle the whole draw calls and AI system.

Honestly, the whole thing with getters and setters alongside some methods not requiring a verb because they're literally just returning a value (like with Vector::length vs Vector::getLength) is why I much prefer C# over Java - properties. You get all the benefits of setters and getters with regular value syntax.

"hair is slowly turning blue from the roots". gottem! Good shit.

This one is so good dude, amazing video and article

Every video, half of what you talk about goes over my head but I can't stop watching.

working in a support role where I had to review what our customers custom interface was doing, comments in code was a godsend. I can't imagine not having comments available.

Sometimes I try to avoid squiggly braces in a general area as a trophy for abstracting the code. I'm still experimenting with abstractions and I don't know how to handle them, but on higher level code, I want it to look like a table of contents, and I want so little code that it shouldn't need a squiggly brace. But maybe I'll quit writing such code one day. I don't know.

I had to check the date on the article, since some points are a bit outdated: -Iterators: in modern C++, you barely see them. In fact, I get almost annoyed in the rare cases I have to actually use them. ranges/views make a lot of things easier and cleaner. Even the algorithms are finally usable enough to justify not writing your own loop (projections are a big part of that). For example: ranges::find(device_list, index, &Device::index); Much nicer than before, where you had to use find_if and iterators: find_if(device_list.begin(), device_list.end(), [index](const auto& device){return device.index == index;}); -streams: thankfully we finally got print and println. And those insanely slow and clunky stringstreams can go die in a fire.

Prodcast is great as always ... i just have one question .. is the Moustach real or u use it to give a mature feel to these analysis ?

I like in theory the concept of either having inputs or outputs but not both, but what if you have a utility function designed to modify an object, such as sort it?

My neck is sore from all the nodding I've been doing while watching this video 😅. It is amazing how many useful ideas (and changes in your own coding behaviour) come from reading other people's source code - more so on codebases that have a large number of contributors.

A vector iterator is really just a pointer. The abstraction makes it look like more than it is.

Team Vertical Space!

In Firefox you can use the reading mode to remove styles from the page.

I’m a space Andy for sure. I like to group lines that makes sense and add space where things change or before the function ends.

I'm not a programmer or coder, but I can appreciate it. I seem to recall that Doom 3 was in development for a relatively long time for the time. I remember an interview with someone saying they spent a long time working on the then-state of the art shadow mechanics. Elegant game though for sure, haven't fired it up in years at this point, played it a lot for a platformer, was a staple as soon as the Halo games felt too dated. I enjoyed some mods with it and reminiscing on that stellar Doom experience before it got too cheesey with modern mechanics. And I seem to recall as well - only vaguely without looking it up - that Doom 3 was the last Id-only release. They started getting bought up after that I think, and wasn't long before whats-his-name went to meta to work on Oculus.

Woah who are you man? Popped out of nowhere on my feed this was very useful gamedev commentary, thank you!

07:10 you need memory address as parameter in c, there is no special syntax for out parameters unlike freepascal

The note around 19:34 about C++'s auto. I tried it for a while in a project, then realized it hides too much information. But what it was hiding was an unordered_map of types that were also pretty long (plus I needed the third argument to say how it's hashed), which was getting annoying to type, read, etc. But then I remembered, oh yeah, you can alias "data types" (for lack of a better term). So I went and did that. Made the code much more easier to read without losing information about what kind of data is being stored.

15:47 totally relatable... the importance of spacing (and I'd also say vertical alignment) is underrated

In regards to writing overly generic code and it being ugly. People need to learn they aren't trying to implement standard library functions, that have to be used by millions of people without knowing their exact use case. Use a specific implementation if you don't need something generic. For instance, from the code he provided, he's defining an allocator type, ala the standard library. Most people will _never_ need to pass a specialized allocator to a class, so why would you write a class for your program that allows you to override the allocator? If you find you need that specific class, but slightly more generic, consider making it templated, but again *this doesn't mean you have to go balls to the wall generic* Just support _your_ use-cases unless you're writing a library intended to be consumed by a large array of people with a large array of uses.

I cant side with Prime on the GetLength vs Length naming argument. Because a function with a return type is something that you Call/Invoke in other words you are "Doing" something in comparison to a field which you access. A field being named "Length" is totally fine because all you do is access it and that is all that happens. When you call a function with a return type you imply logic, if you imply logic you should phrase it as such, in other words it should be "GetLength" implying that you are getting something which might require some more complex logic to be done in contrast to just accessing something. The one special case is properties having get; set; functions, they are in the middle of fields and methods, they should be named like a field but treated as functions, which is why properties are not my favourite because sometimes they just have a backing field and do some minor logic if at all any and sometimes that do statechecks call 17 different methods and then return a value that has been calculated in a cumbersome way, have fun finding out that the reason why your game is running at 12 fps is because you accessed a property every frame instead of caching it because you assumed its just a simple getter.

About vertical spaces it depends. If the language I'm working on has clear code blocks like {} it is fine doing everything together. My mind is trained to read that. But if not like in python, just add vertical spaces. Overall I don't like to waste vertical spaces but I do use vertical spaces if I feel it is needed

const isn't a default for most c like systems for local stack and heap variables because in the old days of you were using an imutable value you'd use a global or preprocessor directive to insert the literal. in reality, practically every system (I've ever used) treats all non-local values as locally const- that's why you need to pass values in by reference (or pointer...) if you intend for alterations in one scope to affect the calling scope directly.. I'm of the school that values shouldn't be const unless they cant be changed or shouldn't be changed for the duration of the scope for some reason. not passing by reference says "im not changing this", passing something as const says "this shouldn't be changed" anything defined as const in a local scope should be just be a literal. when a performance advantage is shown(not in js) I'll maybe change my mind.

Beautiful code is like fine art paintings. You get a range of cubism, realism and impressionism et al that different people gravitate towards

Output parameters are sometimes used in JS. Just have a function accept an object, and have it return that same object, mutated with a new property containing whatever you want

Looping over iterators was basically replaced with the ranged for syntax in c++11

i was a Quake II player in the 2000's and started my interest of programming when i read the Quake II's source code for the first time and i could understand the basics of the meaning of that code and what that does, and i built quake 2 from the source code using visual studio 6.0 and changing strings some texts with my name.. i had no experience in programmming, my first programming contact was BASIC and Delphi before that after this experience i just love C and C++ now i love read games source code.. but some of them are impossible to read (descent II and duke nukem 3d)

We have a rule for our team that you have to document all public methods for a class. You don't need to write title line if the function name is descriptive enough but you have to document non-trivial arguments and you have to define the return value accurately. If you don't like writing documentation, try to mark methods as private as much as possible. The idea of documenting the public interface is similar to design-by-contract in Eiffel language. Without documenting the expected behavior in human readable form, you cannot know how the method should be fixed in the future when you hit some case it cannot handle correctly. Nobody expects you to comment individual lines unless those are a workaround for some external component. In that case, you should document why the workaround exists and why it works because that behavior depends on external component and if the external component ever changes, you need those comments to understand the change in behavior. And if you write any kind of workarounds, try to do feature detection instead of checking for version numbers to decide if the workaround should be applied or not.

Fabien Sanglard is an amazing writer! I strongly recommend buying his books. He only have 3, I have read two so far but these are pure gold. The guy is one of its kind. (Like PrimeTime ofc ;) )

I agree, C langs should make variables const by default because otherwise your source code ends up being 50% const anyway

I feel like function definitions in video on RU-vid about advanced TypeScript are just like the template function definition example in this article.

Beautify?

agreed, immutable by default is the rust hill I am most prepared to die on.

18:30 I make an exception when it's a guard clause, this is the only time I will do an inline if statement: if(shouldNotRun) return;

Back in the time this article really shifted the way I look at code. I'm not grateful enough to the author for what he did there. Nowadays, I still often reference this article to my colleagues when they ask for my views, even if I don't write c++ anymore it still feel relevant.

I seperate all of my programming patterns, data types and data type accessories (like traits and impls) in their own files. Plus I only use the "use" syntax for traits because I have too. This help the code be self documenting. I also make info files for all files describing what happens in them.

Whether a function should have a verb name or not I think comes down to how you think about it. If a function is basically a computed property and the computation is simple / cheap, then just call it the thing. You wouldn't write a math library with functions like getSine() or raiseToPower(). Otherwise, I think it can be useful if the context requires it to clarify how a function gets its value: getFoo() - I don't know much about where foo comes from, but ideally it's not a heavy operation. fetchFoo() - a network is involved loadFoo() - a database or maybe filesystem is involved calcFoo() - a non-trivial calculation either in computational or cyclomatic complexity is involved You might pair these functions with a facade that does caching or lazy loading, and I think that in that case it can depend on context whether a simple getFoo() is preferred, or getFooUsingCache() or lazyLoadFoo(). For factory functions, it depends on whether your language has separate namespaces for functions and variables. In Java I could do `Person person = person("Tom", "Smith", 27)`. But in JS or Python, i would go for makePerson() or buildPerson() or maybe newPerson(). Another exception is what at least in Java are often called fluid interfaces, for example builder patterns like Person.builder().firstName("Fred").lastName("Jones").age(17).build(). These are making up for a lack of expressiveness in the language. Other languages would simply use keyword / named parameters or initializer literals.

Every Java function i have ever written (in 20 years) has the parameters as input only. I'd scream if I saw another dev mutating the state of an incoming parameter. Fun fact, "const" is a reserved word in Java. I really wish it could be put to use for this reason.

I program in QB64PE (a version of QBasic) and I still found this video very useful. Very fast and entertaining 40 minutes!

I come from java, I've always had terrible experiences dealing with c++, but somehow it's getting better. Java is and was very reliable to me because the IDE paired with it let me have an easier time. I still have a huge lack of understanding in c++, and mostly in java, but in java there was way less entropy. I could write the specified code I found online, added my tweaks to it, and once the compiler and I sorted out our differences for 3 minutes, then I got to see how well my code is actually performing. In c++, the compiler just shook it's head after every hurdle I felt I overcame. I could never tell how to solve a specific problem, but now it's that same dance with more interesting complications, which is a good thing. That'll be fixed in due time.

Prompt Engineering Guide Right Here People...Take Notes!!! @ 4:30 honestly...the whole thing is informative, useful and down right interesting! I'm gonna pull this transcript and plug it into my models and spit out a prompt to run this whole Videos thought process: UPDATE COMING SOON!

What is this ,,Effective C++ book"? Is it Effective C++ by Scott Meyers? Thank you!

15:38 adhd rubyist here and I'm very adamantly pro vertical space - vertical rhythm like Prime points out here is one of the most elementary ways to separate ideas and if your code doesn't use it I automatically nonparse it as "blur, complicated, ignore"

During Star Citizen's development they showed some source code in videos called Bug Smashers. I'm no expert by any means, and am simply average with no formal education. I saw a few things in there that made me see just how absurdly complicated the simplest things could be. It makes me glad I don't do any actual game development.

This was mostly about stylistic decisions but real beautiful code is when the solution perfectly matches problem

What makes menus in games extraordinarily difficult and bug-ridden is that you have three different states that need to all be active and live in harmony. Keyboard input, joystick, and mouse. An example: Typically when using a mouse, when you move the mouse cursor over a button it highlights the button. When you move the mouse off the button the highlight disappears. Joystick and keyboards are the opposite. J+K always need a button highlighted. So what do you do when somebody is navigating the menu with their joystick and the mouse inexplicably moves? Or the opposite, what do you do when the user mouse hovers over a button, then presses down on the joystick? It's a million edge cases and you have to pick the least bug-ridden path.

If you want to see well organized and structured code, check out the GLM math library which is a header only library that is designed with the intent to match the primitives of OpenGL's GLSL shader language which is a C-like language. This is a beautiful linear algebra library to use. Now if you need something a little more efficient and or powerful then that's where the power of Eigen comes in. It's structured and written just as nice... Reading through their source code is not all that difficult to parse through. They're much easier than reading through either the STL or even many of the underlying Windows API, DLL driver hell... lol!!!

I had an "Oh wow" moment sometime between 1976 and 1980 when I was reading the source to a player vs. computer game someone wrote, I don't know who. Player was 1, computer was 2, after each turn it switched. So how would I have done it? Probably with an if and 2 conditional assignments. The guy who wrote that program did much better, it in a way that was so beautiful I was stunned, just blown away. One line, one mathematical formula, it was *Player = 3 - Player* It is stunningly beautiful because it works perfectly. If player is 1 now it's 2; if player is 2, now it's 1. Absolutely amazing.

are we still limited by DirectX in windows to provide all interfaces to hardware

27:00 Oh no.. I feel attacked.. why are you looking at me 😂😂😂😂

4:00 I love the realistic take here that code can be beautiful at solving a problem, but you think it's garbage if you don't understand the problem. As software engineers, we have to check ourselves when encountering new code bases. There is a weird tendency to think unfamiliar code sucks.

Lol, I threw away (recycled) my "Clean Code" book, because I don't even want someone to find it in a 2nd hand store :D

That first item about how a function should do one thing... It comes down to a rule i was taught back in the days of the dinosaurs. There is no such number as 2. There is zero, one and many. It is easy to support the last three. But if you decide to support two, then you'll be asked to support three. Then four, etc... Code gets complicated as you add support for more and more single item tasks. IOf you start off supporting many, then going from two, to three, to four, is already built in. I'm currently working on a code base where previous engineers believed that a function should have many jobs. So we have functions with over a thousand lines of code, filled with loops, nested loops, switch statements, and generically named variables, that are reused over and over.. It is a nightmare to support. it is difficult to know if a small change here or there, will have unexpected results somewhere else. If you don't put limits on the complexity of your functions, this is what you get. Once you adopt the concept of one function one task, and one object one resource, everything starts falling into an easy to understand hierarchy.

what theme does he uses?

That dude not considering himself a programmer is either a blatant case of impostor syndrome, or I'm a dumb ass incompetent potato.

You say idPlane I say idPlane We are not the same

With today's large, high resolution, monitors I'm more of a fan of additional vertical spacing. I imagine in the Doom 3 era, screen real estate was more limited.

Does anyone have a link to the idTech 4 coding standards? I did a quick google search but didn't come up with anything promising.

36:57 "it's when someone solves a problem so different from me, it feels like I've unlocked a new way to solve a problem in my brain; has anyone ever had that?" yes! doing tech support where I had to debug code revealed a lot more insights about how to write good code than it did derps about bad code. and that got me into writing code

Remember that the article's commentary person is not a programmer.

36:33 - I actually like the VERB when it's not a field / directly modifiable (eg: private backing field). If it's essentially public, "get" makes no sense (eg: no compute needed for get/set). If computation is needed, adding the "get" makes sense, as it implies an ACTION is being done which could come at a penalty -- especially common in abstractions of a data source for IO

I have code blocks, like I group variable definitions and related code, and then fold regions, dunno if it's a standard for IDEs or just VSCode that implements foldable regions with `// #region validation block` and `// #endregion`.

One of my favorite use of comments is linking sources. Like oh this shit is done that way cause in source X they said that's a good idea

I only use pandas scikit tensorflow and keras for data analysis and ML so most of the time I have no idea what’s going on when talking about other languages than python or sql but primegean is just too entertaining

Reading time combined with comprehension time would be the only quantitative measurements for how "beautiful" source code can be AFAIK.

My mindset is "make it const, so if you pass a const variable into it, it still compiles."

I think you can read Carmack's blog from before 2014 (that's when I read it) which talks about pure functions.

Walls of text without empty lines between chunks is the worst thing ever. Even worse than 2-space tabs. I really can't understand how some people can work with it, because to me it's terribly confusing to even look at, let alone read. If things are separated, you look at it and you instantly get a sort of silhouette of the code, where you can already identify some of the loops, conditionals, definitions, etc. If it's just a jumbled wall of text, you'll have squint and decipher it line by line.

I hate it when people use typedefs to hide complex types.

Beautiful code, like all beautiful things, is in the eye of the beholder. You can describe its features, but you will only know it when you see it

I really like you and I think your stuff is cool. I want to give you feedback but I don't want to be mean / flamy. It's just that when you read an article there are way too many slip ups. It's driving me crazy. Would you consider training a model on your voice and use that to read the articles?

36:40 I think it really depends, for me i much prefer `getLength` if its a method. however `length` if its a property.