Forgot your password?
typodupeerror
Programming Games

Doom 3 Source Code: Beautiful 399

Posted by timothy
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."
This discussion has been archived. No new comments can be posted.

Doom 3 Source Code: Beautiful

Comments Filter:
  • by discord5 (798235) on Tuesday January 15, 2013 @01:39PM (#42593621)
    • It might be beautiful code, but 90% of it just renders a black screen in a horribly inefficient way.
    • For best effect the source code should be read in the dark with a flashlight in your hand.
    • // TODO : add the code for the lightswitch in this class

    I'll be here all week.

    • by djlemma (1053860) on Tuesday January 15, 2013 @01:46PM (#42593719)
      Don't forget that you can't use your keyboard and your flashlight at the same time...
    • by IcyNeko (891749) on Tuesday January 15, 2013 @01:54PM (#42593849) Journal

      John Carmack: The Kanye West of Video Game Programming.

      "Imma let you finish your Dragonborn DLC in a minute, but DOOM 3 has the cleanest source code of all time. OF ALL TIME!"

    • In retrospect, I think timing is what hurt Doom 3 more than the darkness. Doom 3 was released at the same time LCD monitors started to take off, problem was that LCD black levels at the time were horse manure. I saw my friend playing it on his and it looked awful. The unfixed drawbacks of new tech hurt the game's reception among many.

    • by Stormwatch (703920) <rodrigogirao AT hotmail DOT com> on Tuesday January 15, 2013 @02:00PM (#42593941) Homepage

      // TODO : rehire Romero, Petersen, Hall, McGee, Prince.

      There, fixed. The engine may be fantastic, but Doom 3 is a horrible game that can't hold a candle to the previous titles. Or at least it can't hold a candle and a gun at the same time.

      • by Joehonkie (665142)
        Yes, Romero and McGee have a GREAT track record these days...
        • Daikatana and Alice were far from perfect, but they're still more enjoyable than Doom 3.

          • by gman003 (1693318)

            Did you actually play Daikatana?

            I did. I quit before the end of the first level. An absolutely horrid game. Doom 3 I at least lasted about 30% of the way through the game before throwing in the towel. It was mostly the repetition, the constant stuff jumping at you. It's a very fatiguing game - I could probably make it through it if I took breaks to play other games every so often.

            • Did you actually play Daikatana?

              I'll say only this: I wish there'd been an option to murder your companion, then respawn him so you could murder him again.

            • Err you "played" it but quit before the first level!?.. Well I played Daikatana to completion, also Doom 3, and both were fun games. I found Daikatana to be a much stronger design hampered by technical issues, while Doom 3 lacked such a strong design but had a very smooth base. Both games I completed over the course of a couple days of constant playing, perhaps FPS isn't your cup of tea?
          • by X0563511 (793323) on Tuesday January 15, 2013 @03:05PM (#42594923) Homepage Journal

            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.

          • by Ash Vince (602485) * on Tuesday January 15, 2013 @04:02PM (#42595717) Journal

            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.

            • by wiggles (30088) on Tuesday January 15, 2013 @05:16PM (#42596493)

              Did we play the same game?

              The atmosphere was interesting for the first 5 hours of gameplay, then it just got in the way of trying to play the game.

              I got to the point where, every time I'd walk through a door, I'd look to the side and fire into the demon I *knew* was standing there. It was like the line in Last Action Hero where Arnold walks into his apartment, kid in tow, walks into the bedroom and puts a few rounds into the closet door. A ninja falls out of the closet, dead, and the kid says, "How did you know there was a ninja in there?" Arnold says, "There's always a ninja in there."

              The only discomfort I felt was when I was squinting and cranking the gamma up just so I could see what I was doing.

              The story sucked, too. What do I expect from a FPS? Deus Ex, Bioshock, System Shock, and all their associated sequels, etc. etc.

            • That's the thing, the atmosphere was absolutely wrong for the game! That creepy dark shit is what Doom was in the minds of elderly busybodies, but fans of the original expected something zany, fast, and over the top. [doomworld.com]

  • by hugortega (721079) on Tuesday January 15, 2013 @01:50PM (#42593767)
    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)
    • by gbjbaanb (229885) on Tuesday January 15, 2013 @02:02PM (#42593975)

      the concept of the bracket placement there is to emphasise indentation over bracketing. Once you "get" the view of it, it becomes a nice thing to look at, similar to python code.

      I don't use it nowadays (too many coding standards that are written for the bracketing-style) but I appreciated it when I did. There's nothing wrong with the style, so I hope that you pass any code you review written in this style and focus on the important parts like readability of the code, good naming, commenting and the like rather than subjective opinions.

      • by shoor (33382)

        OK, I was a C/assembly programmer, never did much with C++. I always liked the square bracket style, and one thing I found very helpful was putting a short comment at the end of a block after the closing '}', even if it was just to show that it ended a 'for' rather than an 'if'. Example:

        for (;;) /* forever */
        {
        misc code
        if (1==x)
        {
        b

        • Re: (Score:3, Insightful)

          by hermitdev (2792385)

          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 s

    • by Rhacman (1528815) on Tuesday January 15, 2013 @02:23PM (#42594305)
      This is one of those topics of an almost religious fanatacism but I tend to agree. I want my braces to match in the same column and have an easier time looking at code with vertical spaces between blocks of related operations. Functions should still be short enough that they fit on a modern screen (with rare exceptions).

      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.
    • by Darinbob (1142669)

      It's basically what you're used to. I was a passionate "brackets on their own line" style, but my present job's style guidelines do it with compacted way. After awhile I got used to it. It really only bites me when there's a long conditional that has to be two lines; meaning the second line of the conditional and first line of the body have the same indentation but no vertical separation, which I think looks ugly as hell. So I find myself doing things I don't really like to do: splitting into nested if

  • His Comment (Score:5, Informative)

    by phantomfive (622387) on Tuesday January 15, 2013 @01:52PM (#42593805) Journal
    Here is what John Carmack wrote:

    In some ways, I still think the Quake 3 code is cleaner, as a final evolution of my C style, rather than the first iteration of my C++ style, but it may be more of a factor of the smaller total line count, or the fact that I haven’t really looked at it in a decade. I do think "good C++" is better than "good C" from a readability standpoint, all other things being equal.

    I sort of meandered into C++ with Doom 3 – I was an experienced C programmer with OOP background from NeXT’s Objective-C, so I just started writing C++ without any proper study of usage and idiom. In retrospect, I very much wish I had read Effective C++ and some other material. A couple of the other programmers had prior C++ experience, but they mostly followed the stylistic choices I set.

    I mistrusted templates for many years, and still use them with restraint, but I eventually decided I liked strong typing more than I disliked weird code in headers. The debate on STL is still ongoing here at Id, and gets a little spirited. Back when Doom 3 was started, using STL was almost certainly not a good call, but reasonable arguments can be made for it today, even in games.

    I am a full const nazi nowadays, and I chide any programmer that doesn’t const every variable and parameter that can be.

    The major evolution that is still going on for me is towards a more functional programming style, which involves unlearning a lot of old habits, and backing away from some OOP directions.

    One might suggest that every good programmer, if they spend enough time improving, eventually moves toward a more functional programming style.

    • by MobyDisk (75490) on Tuesday January 15, 2013 @02:05PM (#42594013) Homepage

      You remind me of my mom, who ends every political debate by stating that as people become older and wiser they tend toward being Republicans.

    • Re:His Comment (Score:5, Insightful)

      by girlintraining (1395911) on Tuesday January 15, 2013 @02:10PM (#42594083)

      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.

      • Re:His Comment (Score:5, Interesting)

        by jez9999 (618189) on Tuesday January 15, 2013 @02:25PM (#42594349) Homepage Journal

        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.

        • by chispito (1870390)

          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.

          Also, divided government.

      • Re:His Comment (Score:4, Interesting)

        by phantomfive (622387) on Tuesday January 15, 2013 @02:35PM (#42594503) Journal
        It actually follows a predictable patter (YMMV no warranty implied etc):

        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.
        • Re:His Comment (Score:5, Insightful)

          by Alomex (148003) on Tuesday January 15, 2013 @03:23PM (#42595193) Homepage

          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:His Comment (Score:5, Informative)

            by FrangoAssado (561740) on Tuesday January 15, 2013 @04:19PM (#42595901)

            That's a fair point, but you have to pay closer attention to what Carmack wrote:

            I am a full const nazi nowadays, and I chide any programmer that doesn’t const every variable and parameter that can be.

            The major evolution that is still going on for me is towards a more functional programming style, which involves unlearning a lot of old habits, and backing away from some OOP directions.

            He said functional programming style, that doesn't necessarily mean using a functional language -- the point is that he is going in the direction of functional style when writing C++, which would involve, among other things, making as much as possible immutable (hence being a "const nazi").

    • by Joce640k (829181)

      One might suggest that every good programmer, if they spend enough time improving, eventually moves toward a more functional programming style.

      One might suggest that ... but one would be wrong.

      The very best programmers use the right idiom for the job. Sometimes a global variable is the right idiom.

    • by epine (68316)

      One might suggest that every good programmer, if they spend enough time improving, eventually moves toward a more functional programming style.

      Yeah, functional programming was all the rage in 640K with no on-chip cache hierarchy.

      Good grief, functional programming predates the modern OOP idiom. John Backus's FP [wikipedia.org] dates to 1977. I was already proficient in APL which made reading his papers a fairly easy exercise. All this before C++ first appeared in 1983. I wrote all my code for the rest of the decade i

  • by Anonymous Coward on Tuesday January 15, 2013 @02:02PM (#42593965)

    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.

    Anyway, that's just my $0.02.

    • by godrik (1287354)

      "The other thing that rubbed me the wrong way here was public member variables."

      I am puzzled by that as well. I guess his point is that: foo.setBar(foo.getBar()+3); is much more boring than foo.bar += 3;
      I somewhat understand it and I wish we had automatic calls to get and set in C++ like it exists in C# to make core more beautiful.

    • ...there is no good reason to expose bare, public variables on anything but the simplest, most struct-like objects.

      Having also worked on (and lead) large game and non-game projects, I must respectfully completely disagree with you. The compiler might be able to boil someInstance.SetThing( someInstance.GetThing()*2 ) down to a couple of lines of assembly, but my eyeballs can parse someInstance.thing *= 2 much, much faster and (more to the point) more accurately. I think your potential for weird bugs just increases with the complexity of your syntax (and it's no trickier to catch one in a debugger than the other).

      • I'll tell you another reason to use public member variables: OOP doesn't have such a thing as a "public readable" variable, that is, a variable that member functions can change, and which can be read but not changed by non-member functions. The article lavishes praise on const, but this is one form of limited access a lot of OOP languages do not support.

        There's a lot of dogma about coding practices, and I was happy to see the article take some of them on. Brevity is good. So, no useless comments, even

    • by Zan Lynx (87672) on Tuesday January 15, 2013 @04:24PM (#42595951) Homepage

      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.

  • According to id's Doom 3 coding standard, they use real tabs that are 4 spaces. Having a consistent tab setting for all programmers allows them horizontally align their class definitions

    Years ago I had to have this fight with a co-worker. His electric mode in Emcas was writing out everything as a single tab char, and doing the indenting on its own. The problem is, not everything obeyed this style -- not even a little.

    I had to explain to him that since we weren't all using Emcacs, he needed to be sure to l

    • by Hatta (162192)

      I never understood why this was a conflict for programmers. If the white space isn't syntactic, can't your editor just rearrange the code the way you want it? Just run it through a pretty printer before you work on it.

      • by sourcerror (1718066) on Tuesday January 15, 2013 @02:37PM (#42594541)

        Except that will throw off diff.

      • This royally fucks up your version control history.

        Most modern systems have the means to annotate a file - every line - with the revision that last changed it. It's invaluable if you want to work out which revision introduced a particular bug.

        If you all have a whitespace war, every revision that touches the file will touch every line in the file.

        Unless your merge driver is enlightened as well, you'll find it plays hell with your changes as well, every time you pull changes you'll get a conflict.

        It's just ru

    • by jez9999 (618189) on Tuesday January 15, 2013 @02:31PM (#42594425) Homepage Journal

      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.

  • by swillden (191260) <shawn-ds@willden.org> on Tuesday January 15, 2013 @02:11PM (#42594101) Homepage Journal

    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.

  • by Greyfox (87712) on Tuesday January 15, 2013 @02:12PM (#42594121) Homepage Journal
    Most of his admiration appears to be issues of code formatting and lack of comments, not the technical design of the code. He started to lose me even before his rants on the ugliness of STL and boost libraries. Do the objects play well together? Is it easy to assemble them to accomplish tasks in sensible ways and with as little set-up as possible on the part of the user of the library? These were not questions I saw answered.

    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.

  • by caywen (942955) on Tuesday January 15, 2013 @02:16PM (#42594157)

    I found both the article and what JC wrote to be highly informative and rather validating of my approach to things. In software, we usually get little validation because of the wide variety of opinions of who we work with. We've all seen the extremes: The hard core C programmer who can't be bothered with any OO nonsense, and who advocates inspecting the assembly of every method you write. The C++ hippie who sees everything as some kind of exercise in getting the compiler to write the code for you.

    I'm sure most of us follow a more balanced approach. C++ has to be about performance over anything else, otherwise there are plenty of other languages that accomplish much greater degrees of expression, but can't cash the performance check. But, expressibility is important, too, because performance goes out the door once we stop understanding what the code is doing. It's nice to have a language that lets you express things somewhat functionally, yet gives you the flexibility to wring out serious performance.

  • lost me (Score:4, Interesting)

    by j00r0m4nc3r (959816) on Tuesday January 15, 2013 @02:22PM (#42594299)
    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...
    • Re:lost me (Score:4, Insightful)

      by StormReaver (59959) on Tuesday January 15, 2013 @03:39PM (#42595405)

      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.

    • by lorinc (2470890)

      The problem with very talented programers, is that only very talented programers can easily understand their code. I understand it can be problematic in corprate environment when the next Junior comes in and gets totally lost.

      But on the other hand, I guess these guys (The guy from TFA and Carmack) write far better code (performances wise, maintenance wise, etc), than most of the people at any standard IT company.

      At my job (I'm associate professor at a French university), I got to sse a lot of programming st

  • by Khashishi (775369) on Tuesday January 15, 2013 @04:14PM (#42595847) Journal

    Most game companies write engines to make games. The game is the product, so it's not too important how it looks under the cover. iD makes games to publicize engines. So it really does matter for the code to look nice.

  • by TheSkepticalOptimist (898384) on Tuesday January 15, 2013 @04:32PM (#42596047)

    Its easy to go back over a finished codebase, run some static analysis and refactoring tools and clean it up. Chances are this is what was done before releasing it to be open source. I can guarantee this source coded didn't look anything like this during development.

    Of course this is maybe why the game took longer to develop, spending more time making the code look purdy then, say, making the game a superlative gaming experience.

  • by loufoque (1400831) on Tuesday January 15, 2013 @04:48PM (#42596215)

    The Doom 3 code is quite ugly.
    If you want to read good code, try the Linux kernel.

    If that's beautiful, I really don't want to read his "ugly" code...

  • by Digital Vomit (891734) on Tuesday January 15, 2013 @04:53PM (#42596243) Homepage Journal

    "Comments should be avoided whenever possible. Comments duplicate work when both writing and reading code."

    Oh my god, this is the worst programming advice I've ever heard. Is this a joke? Maybe some clever attempt at creating job security?

    There is a terrible dearth of commented code in the world -- especially in the lower-level languages like C and C++ -- and this guy is telling people we need fewer comments in our code?

  • 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.

  • by ravyne (858869) on Tuesday January 15, 2013 @05:19PM (#42596539)
    Came hoping to learn what's so beautiful about iD's code, left convinced that the author (Shawn McGrath) and I have rather different opinions on that... iDs code is certainly not an example of poor code, in a previous job I had the opportunity to view code from around 20 different AAA game studios, its definitely in the top quarter (but that's not saying a great deal); mostly the article is 50 paragraphs of cooing "iD does what I do, guys!" Analysis of what makes said style "beautiful" is subjective at best, and furthermore the author describes himself as "not a coder". For what its worth, IMHO, the best code that I've seen came out of Remedy.
  • by twocows (1216842) on Tuesday January 15, 2013 @05:34PM (#42596721)
    I normally hate most of the garbage that comes out of Kotaku, but this is a really good article. That said, it reminds me a lot of Yossi Kreinin's C++ FQA [yosefk.com]. A good chunk of the article is spent talking about how Doom 3's source is good code despite being bad C++. What kind of language is best written in a way frowned on by the C++ community? Absurd!
  • by Hsien-Ko (1090623) on Tuesday January 15, 2013 @05:49PM (#42596909)
    "All id games before Quake III were written in C."

    Fool! Quake III Arena was also written in C.
  • by EmperorOfCanada (1332175) on Tuesday January 15, 2013 @09:55PM (#42599131)
    Much of code is a matter of taste:
    if(x==1){bla();}

    if(x==1){
    bla();
    }

    if ( x==1 ){
    bla();
    }

    if(x==1)
    {
    bla();
    }

    Are taste. Comments and variable/function names are functional and thus more arguable (but still generally religious). Any review of this sort that talks about code formatting is wasting our time(unless they went way overboard with something stupid) with religious nonsense so I wish he would stick to the benefits of how they pass parameters etc.

    The only time anyone ever "Wins" the code formatting argument is when something else is brought into the argument such as "Format it my way or get fired." or "Format it my way or I quit"

    Nearly every place I worked had someone who always began the argument about coding standards with "I don't care which standard we use as long as we all stick to it." But then they relentlessly argued for their standards and wouldn't give an inch with well structured arguments for every space, comma, and return. Often these standards had all kinds of specific metrics like a certain ratio of comments to lines of code. This way they could point to other people's code and mathematically prove that they sucked. Although the worst were the passive aggressive sorts who would reformat any block of code they touched on to "their" standard which was wildly different from the entire rest of the programming team.

"Mach was the greatest intellectual fraud in the last ten years." "What about X?" "I said `intellectual'." ;login, 9/1990

Working...