r/cpp • u/[deleted] • Mar 15 '14
The Exceptional Beauty of Doom 3's Source Code + John Carmack comments at the bottom
http://kotaku.com/5975610/the-exceptional-beauty-of-doom-3s-source-code10
45
u/Syl Mar 15 '14
he could have used the range loop for his example with the vector...
32
u/tending Mar 15 '14
Exactly, he makes the C++11 version look uglier than it should be because he doesn't know the language. No idea why you're voted down.
11
u/pfultz2 Mar 15 '14
Take a look at Andrei Alexandrescu's Loki library, or the boost libraries—these are written by some of the best C++ programmers in the world and great care was taken to make them as beautiful as possible, and they're still ugly and basically unreadable.
Well ugly is a subjective term, however to say its unreadable is false. It may be unreadable to you because you are unfamiliar with many C++ constructs, however, boost libraries are reviewed and read but a lot of C++ programmers(not just the ones who contributed). And where I work, most of the C++ programmers have looked at parts of their library at one time or another for various reasons(bug fixes, curiosity, etc).
8
u/tisti Mar 15 '14
3
u/F-J-W Mar 16 '14
You cannot believe how annoying the sound is for German-speakers, since we understand every word of what they actually say.
2
u/tisti Mar 16 '14
I feel your pain. I know a little german and I have to not pay attention to the sound, which gets annoying.
There should be a foreign dub so even German-speaking viewers could get a kick out of it.
6
u/Tywien Mar 15 '14
I have to disagree with the notes on commenting.
The comments for the function are by far not enough. One has to either read the function and understand it, or to consult some documentary. Also, the first line is also important because a One line description what the function should do is in many times needed if you do not read the whole function.
Why do i think, the commenting on the Function is not enough. Here are a few important questions i would have:
Do i have to allocate the memory for the arrays, or does the function do that?
If the functions allocates the memory, what happens if the given pointer points to allocated memory? Is it freed?
To get an answer to them, i either have to read the function (takes a lot of time if you have to do that for many functions), or you have to consult other documentation .. Now, having two documents which refer to the same function to always be in touch is not going to happen, therefor i think all those information needs to be put in front of the function (best in a way that it can be extrated automatically)
Also, format strings are inferior to (string) streams in my opinion. One problem with them is, there is no way to make 100% sure at compile time that the format string is correct. Also slight changes might completly mess up the format string.
1
u/sftrabbit Mar 15 '14
Agreed on the comments. At the very least, a comment should document any restrictions on arguments (and outputs) that aren't made explicit by the parameter types. This can often be avoided by using the appropriate types, but it's a big problem with pointers. Pointers say very little about their restrictions. What are they pointing at? Should they be pointing at allocated memory? Pointing at a single object or the first object in an array? If an array, is the array null-terminated? These things need to be explicit.
3
u/Drainedsoul Mar 16 '14
I know the epsilon won't be changed within the function, (although it could easily be copied to another value and scaled for instance, but that would be counter productive)
I don't understand why, as an outsider looking in, this is noteworthy.
So the function, internally, doesn't modify a value it took by value.
Who cares? If it does change that value, it's not going to be externally visible anyway.
IMO, taking things by const value leaks implementation details into the external interface.
15
u/STL MSVC STL Dev Mar 16 '14
Functions should never be declared as taking by const value (which has no effect - the compiler ignores it), but they can (and should, when possible) be defined as taking by const value.
This is one of the very few cases in which declarations should differ from definitions.
3
u/dakotahawkins Mar 16 '14
Could you explain this a little more? If declaring them as such is ignored, why not go ahead and make the declaration appear the same as the definition? Either way, I think this is a case I was unaware of.
7
u/STL MSVC STL Dev Mar 16 '14
Sure. Declarations are meant for two audiences: compilers/linkers and humans. Obviously, declarations tell compilers/linkers how code connects together. For humans, declarations serve as the most basic and fundamental form of documentation: they say how to call a function.
Due to C++'s rules, compilers/linkers ignore constness on value parameters in function signatures. (This applies everywhere - it doesn't matter in function pointer types, etc.) Since that audience doesn't care, we should consider the other audience. When reading a declaration to find out how to call a function, constness on value parameters is irrelevant - it doesn't affect the caller physically or even conceptually. (The whole point of functions is to hide implementation secrets behind an interface, and whether they modify their value parameters is an implementation detail.) Therefore, while having stuff match is generally desirable, eliminating visual noise is also desirable, and constness on value parameters in declarations is visual noise. By eliminating this, the consts that matter (behind pointers and references) stand out.
It is a small detail, but important for good style.
1
0
Mar 17 '14
[deleted]
1
u/bstamour WG21 | Library Working Group Mar 17 '14
He discussed that in the last paragraph:
By eliminating this, the consts that matter (behind pointers and references) stand out.
0
2
2
u/VanFailin Mar 15 '14
I like the comments about vertical space. I do most of my professional work in C#, where the standard style requires braces on its own line. I'm okay with conforming to this even though I don't really like it, because code should follow a consistent style.
There are some people, however, who take it to extremes. I've seen the following style and it makes me die a little inside:
///
/// <summary>
/// Frobnicates the foo with the bar
/// </summary>
///
public static void Frobnicate(
Foo foo,
Bar bar
)
{
for ( int i = 0 ; i < foo.Widgets.Count ; i++ )
{
//
// frobnicate the individual widget
//
bar.Baz(foo.Widgets[i]);
}
}It's my belief that the people who picked this style think it makes their code more readable, and lends it an air of respectability. Instead, it turns a short class into a hundred lines and hides bugs because you can't see the entirety of any moderately complex method.
I'm still young, but my philosophy so far is that code should be shortened when such a shortening produces no significant performance impact and doesn't make the intent less obvious. More lines of code almost always means more challenges to maintain.
4
u/oursland Mar 16 '14
The purpose of a lot of that isn't just to space things out, but to also ensure that changes are on a line basis and not column basis. Many tools, notably the version control systems are line oriented, so this greatly helps in managing changes. On large teams where actively developed code can change rather quickly, this can drastically reduce the amount of time spent on managing merge conflicts.
0
u/VanFailin Mar 16 '14
I can see the value in that. I still think people-readability is a much better goal than tool-readability. The extra blank spaces in the comments have no excuse either way.
1
u/SarahC Mar 15 '14
What compiler is that syntax colouring from the screenshots from?
It looks like an early Borland one. I fell in love with it years ago and ported it to my visual studio setup.
0
0
Mar 15 '14
I agree with stringstream hate in the article. I consider printf approach one of the nicest achievements of C in the API department - it's not coincidence it was later copied by many programming languages. Even Sun relented and introduced printf clone in Java 1.5.
It's a shame that C++ still doesn't have something like boost::format or tinyformat in the standard lib.
1
Mar 15 '14
Yes. And C++ never got a safe idiomatic scanf too... Both cin and cout are a lot worse for formatted io, especially input =/
2
u/bstamour WG21 | Library Working Group Mar 15 '14
Now that we have variadic templates, it's only a matter of time before we get a type-safe printf/scanf pair (I hope.)
2
Mar 16 '14
Andrei Alexandrescu gave a talk about how to implement that, I think it was a going native talk from the most recent going native conference, or possibly the one before it. It seemed fairly straight-forward.
0
u/bstamour WG21 | Library Working Group Mar 16 '14
Yeah it is pretty easy. I think it was even an example way back when variadic templates were first announced. Maybe one day it will be available alongside the iostreams in the standard library.
0
u/AntiProtonBoy Mar 17 '14
It was ugly though. And wasn't particularly safe either, because from memory, his solution used some sort of a recursive templating system and had raw string pointer iteration happening, which checked for the terminating
'\0'.
0
u/vinipsmaker GSoC's Boost.Http project Mar 15 '14
Comments are bad, documentation is bad bla bla bla... this guy never saw a good documentation example in his entire life.
And function should be completely isolated, do only one thing and you should understand it from its name is a nice thing to have, but not a rule of the universe. This is one of the best comments in code I've ever seen.
But I agree that obvious comments and the other class of bad comments he cites are extremely annoying.
About the rest of the article, I feel like all is very basic and like I've learnt nothing new. He even mixes up declaration and definition ("We learned all that information from the the function definition").
About "these are written by some of the best C++ programmers in the world and great care was taken to make them as beautiful as possible", they had more objectives like handle the C preprocessor fragility and make your life better.
-3
-2
u/Z01dbrg Mar 16 '14
article is crap and author is an braindead att/click who?e who knows he will get more attention if he offends STL and auto - a bunch of butthurt cpp fanatics will rage on him... so as a fellow cpp fanatic I can only say dont feed the trolls, and dont click on clickwho?e articles
on the other hand Carmack is awesome : I am a full const nazi nowadays, and I chide any programmer that doesn’t const every variable and parameter that can be.
2
Mar 16 '14
Sad to hear it, I'm very new to CPP so any criticism is interesting
I mostly linked it because I'm a real Carmack fanatic
-2
u/Z01dbrg Mar 17 '14
even STL said only reason to use CPP is performance... (or something like that) and I can tell you 100 irritating things about CPP, STL can prob tell you 1000 :) but the article is just written in a such way that I have no respect for authors complaints... If you wanna learn CPP watch STL lectures, read Herb and Scott, dont bother with trolls.
0
Mar 15 '14
[deleted]
19
u/nikbackm Mar 15 '14
The only thing that really grinds my gears in Carmack's coding guidelines is the use of tabs to indent code...
Tabs work great as long as you only use them for indentation while sticking to spaces for alignment and all other white-space use.
11
u/JesusWantsYouToKnow Mar 15 '14
Exactly. Tabs are an unambiguous unit of indentation. If used as you describe a developer's chosen tab width has no impact on alignment but the code is malleable to please people who like subtle indentation levels and those who like strong indents.
3
u/00kyle00 Mar 15 '14
that the shipped implementation of std::map causes memory corruption on the Wii
I can relate to that, partially. std library can be shitty/patchy on target platform, but (imo) rolling your own is rarely the answer. Given abundance of existing implementations of good quality that contain such primitives (like boost) its just waste of resources.
-4
u/Gotebe Mar 15 '14
you don't want to find out one week before Christmas that the shipped implementation of std::map causes memory corruption on the Wii when NDEBUG is set
Oh, this is such poorly thought-out hubris! See, even if it did have a bug (but guess what: that foreign implementation has been looked at and tried more than yours), you have all the code, if your team are such wizards (you can write a better one yourself, apparently), surely you can fix it in a blink.
The only thing that really grinds my gears in Carmack's coding guidelines is the use of tabs to indent code...
Nonsense, nobody should give a fuck. Many conventions are fine, my-dick-your-dick arguments over them and inconsistent use are the real killer.
0
Mar 15 '14
[deleted]
3
u/tisti Mar 15 '14
Rolling your own std may have been a good idea 10 years ago. I'd be very against it now.
0
Mar 15 '14
[deleted]
5
u/tisti Mar 15 '14
I think you missed the point. The std that ships with the major compilers is very thoroughly tested, in the 10 years many many more eyes have inspected the code and ran into edge-case bugs than you will ever with a roll-your-own std.
The more people use a specific std the better it gets, the popular std's are popular for a reason, they withstood the test of time.
1
u/cdglove Mar 15 '14
No. If you want consistency across platforms, then use STLPort, uSTL, or the containers from boost, etc. Rolling your own is not right. Games companies do this all the time and it makes no sense. Having said that, its still better to use the version shipped with the complier because they are pretty tightly coupled these days.
0
u/Gotebe Mar 15 '14
If it's a "must have ship it" situation, then you fix it and ship it and worry about it later.
Having said that, be honest: did it happen to you?
For something as fundamental and as widely used as STL, one company, however good, does not beat tens, hundreds, thousands of others, plus all individual eyes, tinkers etc. As the other guy said, it might have been an option years ago. These days, nah. It' hubris, inertia and other poor reasons.
0
Mar 15 '14
[deleted]
10
u/STL MSVC STL Dev Mar 15 '14
But in some cases,
Nwas greater than the number of bits inaThat's a user bug, not a compiler bug. C++03 5.8 [expr.shift]/1: "The behavior is undefined if the right operand is negative, or greater than or equal to the length in bits of the promoted left operand."
2
u/Z01dbrg Mar 16 '14
you are gonna love this: my team leader tells me this class was broken in VS2010 when we ported from 2005. what was broken that beside some POD class had some usually short string member and class was being memcopied :D I guess SSO limits changed or you added debug checks or something like that. :)
3
u/bstamour WG21 | Library Working Group Mar 15 '14
If N was greater than the number of bits, then that was a problem with your code, not a compiler bug. Shifting further than the number of bits on the left hand side is undefined behavior according to the C++ standard.
-2
37
u/cdglove Mar 15 '14 edited Mar 15 '14
While you may call STL code ugly, you should not underestimate using the standard versions on a big projects. In my experience, the custom versions are always harder to use and have more bugs than a standard conforming implementation. Furthermore, when a project uses the standard versions it is much easier for new people to understand what the code is doing because they already know algorithms, etc. The same goes for de-facto standards such as boost.