Long analysis of Doom III's source code on Kotaku

[Grall]

...Written by another games programmer. I'm sure that for someone who actually knows how to code it's a fascinating read. I don't understand much, though.

Also, John Carmack himself weighs in in the comments with a fairly long contribution himself. Please, go take a look.

---> http://kotaku.com/5975610/the-exceptional-beauty-of-doom-3s-source-code

 

[Davros]

I'll start shall i
comments are good

 

[ebola]

Code should be self-documenting. Comments should be avoided whenever

avoid comments?!
this means insanely long function/variable names instead of comments

is that really considered better than notes explaining in english what its supposed to do?

they rolled their own generic containers, string class, etc. They wrote them much less generic than the STL classes, presumably to make them easier to understand.

I agree with this. its easier to write templates that only do what you need, instead of having multiple levels of adapters being all things to all people. i much prefer rolling my own collections

 

[pcchen]

avoid comments?!
this means insanely long function/variable names instead of comments

is that really considered better than notes explaining in english what its supposed to do?

Yes, because comments quickly become outdated (and can be misleading), and many people don't know how to write proper comments.

I think comments should only be used to explain for something that's not obvious (and can't be made obvious in code), such as "why" doing something, instead of explaining what the code is doing (which, preferably, should be self explaining from the code).

 

[Davros]

this means insanely long function/variable names instead of comments

And theres nothing wrong with descriptive variable names either..
most ide's wil autocomplete them for you so there is no extra typing

Yes, because comments quickly become outdated

As opposed to languages which never become outdated. Lisp / Ada / Cobol say hello

I think comments should only be used to explain for something that's not obvious

Obvious to whom ? you or the guy who has to convert your code to another os/language 30 years from now ?

 

[AlexV]

That article is at best an opinion piece stated in a completely unwarranted authoritative tone. And whilst taste is really non-debateable, I personally found it rather cringe-worthy. Emphasis on personally.

 

[pcchen]

As opposed to languages which never become outdated. Lisp / Ada / Cobol say hello

You misunderstood. What I mean is many times codes under a comment could be modified without anyone modifying the comment. At first it may not be significant modification, so no one bothered (or thought it's necessary) to modify the comment, then over time the comment can be completely different from the codes it supposed to be, well, comment.

Obvious to whom ? you or the guy who has to convert your code to another os/language 30 years from now ?

If one have to rely on a comment to "convert" a code, then he/she is probably not the best one for the job.

[EDIT]Add some examples to illustrate my point:

1. redundant comment:

float computeTrackLength()
{
    // compute the length of the track
    return radius * 2 * M_PI;
}

2. not very useful comments:

float computeTrackLength()
{
    // compute the circumference of the circle
    return radius * 2 * M_PI;
}

3. A better comment:

float computeTrackLength()
{
    // the track is a circle with radius
    return radius * 2 * M_PI;
}

 

[Davros]

and what is M_PI ? I take it its a constant defined somewhere else as pi (why the M_)
ps: all circles have radius's (sorry cant spell the plural )

 

[Billy Idol]

I am a bit shocked about the comments stuff!

In our business, we need comments. Some algorithms in scientific computing are so complex that it would take extremely long to decode without a comment (which often even cites a paper).

But I agree that a proper IN/OUT regulation of variables in function is beautiful and helps.

Also a proper style guide and some basic guides for the declaration of variables (which should indeed be self commenting) and function names helps a lot to.

 

[AlexV]

Radii IIRC. It's M_ because it's a C macro from a set of Math-defines (basically some helpful constants). It lives in math.h (or cmath for C++ properism).

 

[pcchen]

ps: all circles have radius's (sorry cant spell the plural )

That part should read "r = radius."

Actually I agree that if an algorithm is complex, there should be some comments explaining what it does, but even so that should be brief. For example, in my previous example, it may be like this:

float computeTrackLength()
{
    // the track is a circle with r = radius, where its circumference is C = 2 * pi * r
    return radius * 2 * M_PI;
}

This way, when someone reads this code, it'd be clear that why this function, while named "computeTrackLength," computes the circumference of a circle (and how, if he/she doesn't know how to compute the circumference of a circle)

 

[Davros]

So then we all agree
Now if anyone says programs should also be flowcharted, i'll kill them on sight

 

[Alexko]

So then we all agree
Now if anyone says programs should also be flowcharted, i'll kill them on sight

When I was an undergrad, I took a mandatory course in software development in which we had to make a whole bunch of UML diagrams for every piece of actual code.

It's hard to overstate how much I fucking hated that.

 

[PixResearch]

Thanks for the link - very interesting read
If there's one thing I took away from it it's that I really should use const much more than I currently do...

Unfortunately reading Carmack's response and following the link to his blog caused two things to happen:

1) Bought a copy of the book "Effective C++: 55 Specific Ways to Improve Your Programs and Designs" from Amazon.

2) After reading his post on Static Code Analysis (http://www.altdevblogaday.com/2011/12/24/static-code-analysis/) I tried Visual Studio's /analyse on a large code base I'm working on... I suspect tomorrow is now going to be spent working through that rather large bug list! lol

 

[Novum]

In my opinion the author is wrong about setters/getters. They are there to have the possibility to do internal changes to a class without changing the external interface (e.g. making it thread safe). Directly accessing member variables is almost always bad.

 

[idsn6]

If you want a real analysis of the Doom 3 engine, follow the link from the underwhelming Kotaku article to Fabien Sanglard's: http://fabiensanglard.net/doom3/index.php

 

[Laa-Yosh]

I've forgotten quite a lot about programming and don't really feel like I'd ever like to get back into it, but I still find it kinda strange that Kotaku has a man with 3 games under his name to write about source code from someone like Carmack...

 

[MrGaribaldi]

Comments in source code is always an interesting question, as what is obvious to you might not be obvious to someone else... Especially when the code is written by people from different fields...
But agree with the last example from pcchen as a very good example of how to do it.

Though I think an added comment to the function declaration for use with doxygen or such would be good. (But can not say I'm good at those myself )

Will also recommend Cppcheck for static code analysis. It's quite effective, though can take a bit of time when run on very large code bases.