This source code looks perfectly legible to me. In fact, for C, it's the equivalent of T-Ball.
Nicely and consistently formatted, relevant comments, sane structure, along with decent fn, and var names.
What is your definition of "good, readable code?"
P.s. I've emailed the mods, but a currently dead child comment from a new account states essentially the same thing (my vouch was insufficient to rez): https://news.ycombinator.com/item?id=40742493
I must admit, despite programming games for a long time commercially, that code is not very clear to me.
If the code is perfectly legible to you, can you explain how R_DrawPlanes draws the ceiling and the floor, step by step, as a practical illustration? How long did it take? It took me maybe 5 minutes to understand how it works.
I think just about every function I read every day is easier to comprehend. And I review a lot of game engine code. I make no claims I’m a fantastic programmer, of course.
that function contains four if statements and all four of them use indentation, and the same brace indentation style is applied with perfect, machine-like precision throughout the entire file
the last two look like this
if (fixedcolormap)
ds_colormap = fixedcolormap;
else
{
index = distance >> LIGHTZSHIFT;
if (index >= MAXLIGHTZ )
index = MAXLIGHTZ-1;
ds_colormap = planezlight[index];
}
that's indentation
maybe you're running some kind of browser extension that screwed up the formatting of the code in your browser. or maybe the problem is that the indentation uses 8-space tabs and your browser is rendering the tabs in some other way. (when i initially pasted the code in here, hn converted them to spaces.) what browser are you running? the code looks fine in linux firefox
the only exception to this perfect syntactic consistency in compound statements is that in two cases (lines 137 and 237) there are unnecessary braces around a single statement, turning it into block that could have been just a simple statement. i don't know if this is an artifact of the code's edit history or what
What? What's a pretty severe nit pick. Especially for 30 year old C code.
They didn't have no gofmt back then. We are spoiled today with the extreme consistency :) the skill of reading code includes reading even when it deviates from one's own preferred formatting (within reason, maliciously formatted code can be challenging, to say the least).
I must respectfully disagree about this being an issue worthy of anyone's attention, especially yours and mine.
It could use more verbose variable names and comments to give the reader more context. So the bus factor is very low.
If this programmer leaves the team and their large codebase like this is left behind, it will likely become a calcified legacy monolith of code that is expensive to maintain.
Today, such code would not pass code review and possibly some automated pre-submit testing (Halstead’s metrics, Microsoft’s maintainability index, etc) in the AAA companies I worked for that cared about code maintainability.
It’s not specifically about formatting or syntax. It’s more about whether a different programmer can look and understand exactly what it does, and what cases it handles, and which it doesn’t, at first glance. And the other programmer can’t be Carmack-experienced or grey beards — it has to be the usual mid-level dude.
The code could even be written in a self-documenting code paradigm with parts extracted into small appropriately named functions. And it doesn’t need to be done to some perfectionist extreme, just a little bit more than what Carmack did. It just can’t be what we jokingly refer to in the industry as academic code — made for one author to understand and for every other reader to be impressed but not work with.
1993 was a different time, more code was academic, most of it was poorly documented. And there were good reasons not to have function call overheads. We even used to do loop unrolling because that saves a jump instruction and a few variable sets (you only increment the program counter as you go). So some of the reasons why this code is the way it is are good. But in readability, we have evolved a lot in the games industry.
So much so that Doom’s code is pretty hard to read for most programmers. I asked around at work, in a large AAA company, and the consensus is that it’s archaic. But you know, it’s still good code, it did what it had to do, I’m not bashing it.
In the games industry, we generally try to write code that can be maintained by an average programmer.
I would at least add more comments for context. Some teams have other ideas, like self-documenting paradigms with small functions and descriptive names.
If a typical programmer doesn’t at a glance understand what each line of each function does on screen, what all the variables mean, what changing any line would do, what is the usual data flowing through the function, and what are the limitations of the function, then it either can’t be maintained quickly and cheaply, or maintaining it will introduce unforeseen bugs.
But the key point is to not have a codebase that only a small core team can maintain.
If you want to see examples of the difference between this and modern in C-like code, see Unreal Engine’s source code. It will generally, at least in areas of frequent change, be much easier to read. I would expect a mid-level programmer to understand 90% of UE’s functions in 10 seconds each. And more experienced programmers usually understand most functions they’ve not seen in UE in a couple of seconds.
That’s not the case with Doom code. It took me up to 5 minutes to understand some of them. That means significantly worse readability. And I work in C++, C, C#, and other programming languages at a quite senior level in AAA games. So I don’t think this is a skill issue. It could be, of course.
https://github.com/id-Software/DOOM/blob/master/linuxdoom-1....