Doom 3 Source Code: Beautiful 399
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."
Limiting your market (Score:5, Insightful)
Re:Else ifs - yuck (Score:4, Insightful)
Are you an idiot? Case statements don't do the same thing as if else. The example in the article does some floating-point compares. How do you represent that as a case statement in C++? Come on, I'm waiting. Oh, that's right. You can't.
Case statements take an integer value and switch based on it. You cannot have case (dot < -epsilon) or case (dot > epsilon). Got that? Good.
wonder what else ID missed
If you think Carmack "missed" something, take a deep breath, count to ten, and figure out what you missed.
No, he's not perfect - I found a bug in DOOM 2 that he never tracked down - but until you prove yourself STFU about how Carmack may have "missed" something you only learned on Stack Overflow anyway. Carmack is a Level 99 Wizard while all you can do is read the descriptions of the kinds of spells he can cast.
God people like you are annoying. Shut up and think, and you might learn something.
Re:Limiting your market (Score:4, Insightful)
Re:His Comment (Score:5, Insightful)
One might suggest that every good programmer, if they spend enough time improving, eventually moves toward a more functional programming style.
Good programmers don't move towards any one style, they become familiar with all of them and use them when and where appropriate. Just like computer geeks. You find Linux one day, install it, then fall under the spell of believing this year will be the Year of the Linux Desktop. But after awhile, you reach the second plateau of understanding -- Linux is good for some things, but not everything. The third plateau is no longer caring which tool you use, as long as its the best tool for the job.
Most of His Admiration Is Not Technical (Score:5, Insightful)
And a note on the relative evil of comments; bad or not, well placed comments have saved me an awful lot of time when taking on maintenance of code bases in the past. Most of the time they can't present a design document to you, or if they do it covers the design at the start of the project, a decade and a half earlier. Code is a method of communication between two programmers, but if the code doesn't suffice to illuminate the design the original programmer had in mind, I'd really appreciate a comment explaining his thoughts. Especially if the particular section of code is complex, and especially if I'm the guy writing it and end up being the guy maintaining it a couple years later.
Re:Not the best analysis (Score:5, Insightful)
The whole concept of self-documenting code irks me too. Too often programmers use it as an excuse for not writing comments at all. Of course the code should be written clearly enough to the point where you don't need the comments to understand how the code will execute, but I don't think you should count on that as showing what and why that block of related operations is doing what it does. Comments can certainly be overused and underused and while commenting every single line is absurd in most cases, not commenting under the umbrella of "self-documenting" code can be detrimental as well.
Re:This is a must ... (Score:4, Insightful)
Heh... if they're dictating tab width, they're doing it wrong. If you must have a certain tab width, you should be using spaces for everything or you lose the whole benefit of tabs - letting people choose their preferred indentation size.
Use tabs for indentation, spaces for alignment. That way you'll never go wrong. Looks like this was one of the less "beautiful" things about the Doom 3 code.
Re:His Comment (Score:5, Insightful)
Re:Beautiful code but (Score:5, Insightful)
I did. No issues. Hint: The dark parts are supposed to be dark.
Re:Else ifs - yuck (Score:4, Insightful)
Case statements can be optimized using jump tables.
Any semantically-equivalent code (that is, two instances of code that "does the same thing") can be optimized to the same set of instructions. It's just a matter of whether or not the optimizer can figure that out.
Re:Beautiful code but (Score:5, Insightful)
Speak for yourself. I thoroughly enjoyed Doom 3. Quake 4 as well. I actually modded in more self-shadowing and flashlight shadows into Quake 4 - wasn't dark enough.
Re:His Comment (Score:5, Insightful)
4) The programmer discovers that functional languages do not provide enough access to basic data structures to write high volume state of the art applications, and rewrite many key portions of the code in C thus coming full circle.
Whoever writes a functional language that understands arrays and pointers will rule the world.
Re:lost me (Score:4, Insightful)
3.) tight vertical spacing is archaic and stupid, unless absolutely necessary for some display reason
After spending the first several years of my C programming life using K&R syntax, I eventually realized that many of the problems I had maintaining my code came from trying to parse through the dense insanity of tight vertical spacing (and other K&R style issues that originated from constraints that haven't existed in many years).
When reading Linux source code, the first thing I have to do in order to make the code intelligible is reformat it away from K&R. K&R is perhaps the single ugliest coding style I have ever seen or used.
Re:Beautiful code but (Score:5, Insightful)
Re:Mostly right, but a few problems. (Score:5, Insightful)
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.
There's zero difference between a public getter/setter pair and a public variable. Encapsulation and future proofing the interface? In a game codebase? You'll never use it, and if you did need it the code editor can search and replace for you. Meanwhile, writing piles of getter/setter functions is a waste of time. Unexpected modification of public values doesn't get any better when its done through a setter function.
Re:Beautiful code but (Score:4, Insightful)
F.E.A.R.s sparse cut sense were better then the lights on lights off. There were also stretches in F.E.A.R. through well lit area's that were devoid of enemies. Only to be ambushed later. I wouldn't trash on F.E.A.R. so much.
I only played the 1st version and not the expansions.
The things he likes are the things I hate (Score:5, Insightful)
He loves the lack of white space, I hate it. Cramped code is irritating to read. If you want to take up less vertical space, reduce your font and increase the whitespace. You have a better sense of the separation of statements, stronger scoping and less room for error.
He also loves the lack of comments. I remain firmly in the camp that if you eschew comments as common practice, you're an idiot and you should stay away from programming on big teams.
It's not a clarity of code issue. I expect your code to be clear, too. But even after 20 years of programming, I read English faster than I read code. A description of an algorithm in English is going to be more terse than the code that implements it. Your code has to account for edge cases, but I probably just want to know what the code does and how the code does it at a high level so I can get a sense of the system and architecture. A descriptive method name only tells me WHAT the method does, not the manner in which it's done.
English (any natural language, really) is a powerful language with extraordinary expressive power. I don't understand why programmers are constantly trying to sweep it under the rug. Don't fill your code with useless comments like // increments the counter by 1, but if you're doing a non-trivial mathematical calculation that takes a whole method to encapsulate it, let me know what I'm getting in to.
Code comments--especially system level comments--should include the name of the author or current maintainer, as well. I tag my methods with my name and the date that the code was put in so people know where to go if there's trouble. They don't have to hunt through perforce time-lapses to see that I checked it in, they just email me.
And have some consideration for the new guy on the team, or the team that has to use your code 5 years in the future. They can't ask you questions, the context of the situation is lost, the code-base might be in the middle of being re-purposed (common in the game industry--which is where I am); comments are essential to maintainability. Man, I do code reviews and people often manage to forget exactly what they were trying to do, and it's only been a few hours. We always work it out, but if there were a comment, we wouldn't even have to spend THAT time.
Use comments. Use them wisely. It makes you a better programmer because you're wasting less of OTHER people's time.
Re:Else ifs - yuck (Score:4, Insightful)
case statements are not faster than if-else statements
This is one of the worst comments I've ever seen with an Informative mod on Slashdot.
Most of the time, switch / case statements are optimized by the compiler to use jump tables that are much more efficient at runtime than evaluating expression after expression.
Re:Solaris Code (Score:4, Insightful)
l would agree here. I only saw some bits of it but comparing code between Linux, BSD, and Solaris that did the same thing, the Solaris stuff was definitely the easiest to understand. Linux I found to be the most obtuse in comparison. Though to be fair the code bases are so large with so many authors that some code may look great while others are awful. Solaris I think wins just from having coding styles and standards.
Re:Not the best analysis (Score:5, Insightful)
My take on comments:
Write the comments first, describing the overall goal, inputs and outputs.
Then write the actual code that implements the comments.
Re:Not the best analysis (Score:3, Insightful)
While I prefer this style of bracing, the superfluous comments violate the D.R.Y. (Don't Repeat Yourself) principle. Might as well add a comment "break when x is one", as well. (also "forever" after "for(;;;)" or "while(true)" is again unnecessary and repetitive). I know your example is contrived, but these do serve as a prime example of bad comments. What's even worse is when down the line, "they" decide that you should break when x is two, but the comment remains unchanged. The point of comments that should be hammered home is: tell us not *what* happens, but *why* it happens.
The reason I like the open & close braces, with proper indentation, is that at a glance I can see where the block starts and ends. If you cannot see the start of the block and the end at the same time, the block is too large and should be refactored such that you can.