Posted
by
timothy
on Tuesday January 15, 2013 @12:33PM
from the but-deadly dept.

jones_supa writes "Shawn McGrath, the creator of the PS3 psychedelic puzzle-racing game Dyad, takes another look at Doom 3 source code. Instead of the technical reviews of Fabien Sanglard, Shawn zooms in with emphasis purely on coding style. He gives his insights in lexical analysis, const and rigid parameters, amount of comments, spacing, templates and method names. There is also some thoughts about coming to C++ with C background and without it. Even John Carmack himself popped in to give a comment."

It's just a personal point of view about coding style... some things like vertical spacing using the braces (at the section "Doom does not waste vertical space") are just the opposite of a readable source code (just in my opinion, of course, as someone that makes a lot of source code reviews of other people)

I've developed for large game and non-game projects, and each needs a different approach. Console games especially have serious problems with dynamic memory allocation (they don't typically have swap files and can die due to heap fragmentation) so you have to avoid a lot of convenience libraries like STL.

STL, however - especially in newer compilers that support C++0x - is actually quite good and is very, very robust. It's a good way to avoid a lot of the memory management bugaboos that happen when you *are* doing lots of dynamic/heap allocation. So I would very much endorse a sane amount of STL use in desktop code.

The other thing that rubbed me the wrong way here was public member variables. Since inlining and move semantics make getters and setters essentially free, there is no good reason to expose bare, public variables on anything but the simplest, most struct-like objects. The biggest source of weird, hard to trace bugs in our code at the game studio were often due to people modifying public members of other objects in unexpected ways or at unexpected times.

Having public, non-const member variables actually hurts a principle the author supports, which is "Code should be locally coherent and single-functioned". This means that an operation should do one thing and put you in one of several known and easily discoverable states, even on failure. That is, if I say, make this guy do X, then either he does X or he fails and ends up in a known state. If that state is available in the form of modifiable public data, then his state can get messed with at any point along that path by some other code, and the final state (in cases of success and failure) is not fully known. At the very lest, making data private means that only certain code paths can modify the data, and it's much easier to keep state coherent.

I really liked this bit, because it's something I've been really focusing on for the last year or so, and I think it has significantly improved my code:

Comments should be avoided whenever possible. Comments duplicate work when both writing and reading code. If you need to comment something to make it understandable it should probably be rewritten.

Comments can be useful, IMO, but primarily only for generating documentation (think Javadoc or doxygen, etc.). Other exceptions include bits of code that perform highly-optimized mathematical calculations, in which case I think the best solution is to write a proper document and then add a comment linking to the document, and bits of code that do something which apparently could be done differently but for some other reason must not -- assuming that explanation doesn't belong in the doc-generating comments.

Other than that, I find it makes my code a lot better if every time I find myself wanting to write a comment to explain some bit of code's purpose or operation, I instead refactor until the comment is no longer necessary. Often it's as simple as taking a chunk of code from one method/function and pulling it out into another with a well-chosen name, or else introducing a variable to hold an intermediate value in a calculation, with a well-chosen name. Sometimes the fact that a bit of code is hard to explain is a strong indicator that the design is wrong, that stuff is mashed together that shouldn't be.

The bottom line is that I've found eliminating comments does more for improving the readability of my code than anything else, and I've gotten similar feedback from colleagues whose code I critique by pointing out that they can eliminate their comments if they refactor a bit.

after the first three conclusions, and i stopped reading so i can't speak for the rest. should be: 1.) const as appropriate, not "const everything possible". const can fuck you hard in OOP if you use it wrong, 2.) you can never have too many comments, and 3.) tight vertical spacing is archaic and stupid, unless absolutely necessary for some display reason

if this guy was interviewing here and mentioned all the things in his article, i probably wouldn't hire him. too much "religion", as it were, which is a huge red flag for me because it's usually masking something...

Yet the fourth plateau is the realization that if one vendor becomes extremely powerful, it tends to create huge barriers of entry for others and so your choice is reduced, sometimes drastically, and therefore it can be a good idea to just arbitrarily support competition even if what everyone uses is good enough right now.

1) A programmer discovers scripting languages and loves them, because they are so easy to write. Which is true.
2) The programmer discovers OOP, and realizes it makes code so much easier to read. Which is also true.
3) Then the programmer discovers functional programming, and realizes it makes it so much easier to avoid bugs. Which is also true.

You might say Python tries to combine all three of these features, which is true, though I offer no opinion on how well it does.

Daikatana and Alice were far from perfect, but they're still more enjoyable than Doom 3.

I think you hit the nail on the head there, but possibly not in the way you mean.

Doom3 was an absolute masterpiece of atmospheric gaming, but it was just too much. It set your nerves on edge in a way that meant playing for more than an hour or so was just too stressful. I love the levels, the monsters, the story (ok, its basic but what do you want from a FPS) but I just find playing it burns me out too quickly. It is just too good at making you feel uncomfortable and claustrophobic without any respite.

I was just thinking back to Doom as I type this and from memory the big difference is that Doom had more variety with some levels set outside or in huge cavernous high ceilinged spaces. This variety is what made it great as it certainly had plenty of claustrophobia inducing levels too.