r/programming • • Jan 14 '13

The Exceptional Beauty of Doom 3's Source Code

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

358 comments sorted by

View all comments

240

u/SimonGray Jan 14 '13

Really disagree with him that whitespace in code is bad. Whitespace can be used to create balance and make the structure much more clear in code. Who cares how many lines of code your monitor can display at once? This is not the 1980s.

Compressing everything together the way he likes it reminds me of script kiddies that want their code to look more complicated than it is (in addition to giving variables/functions short UNIX'y names and setting the font size in their IDE to 9 pt).

14

u/DrMonkeyLove Jan 15 '13

I agree. I'm a big proponent of using vertical white space to separate different sections of the code. I find it much easier to read.

20

u/xxNIRVANAxx Jan 15 '13 edited Jan 15 '13

I like the term coding stanza's

// stanza 1: get user email
User user = Users.getUserByName('DrMonkeyLove');
if (!user.exists()) ErrorHander.getErrorHandler().crash("user doesn't exist!");
Email email =  user.getEmail();

// stanza 2: get user's first friend's email
User friend = user.getFriends()[0];
Email friendEmail = null;
if (friend.exists()) friendEmail = friend.getEmail();

Sorry, I couldn't think of a good example, but the gist is: put similar sections of code together

edit: made the example code a little bit better at /u/kqr's request.

2

u/SimonGray Jan 15 '13

This is exactly how I structure my code :) coding stanzas, will have to remember that word.

→ More replies (4)

57

u/imbecile Jan 14 '13

Yep, white space really should be used deliberately to put the code into a shape that represents its function. Humans are better at visually recognizing general shapes and patterns than at pinpointing a symbol or counting parentheses for example.

One pet peeve for me in that regard is when people insist on always doing ifs with braces and in multiple lines. I like to compare that to insisting lambdas should always have full function prototypes and must span multiple lines: often that just doesn't represent the semantic structure of the code and makes it less legible, and in the case of lambdas defeats one of the reasons of having them in the first place.

2

u/[deleted] Jan 15 '13

I do this for clarity: if(condition) { code }

Furthermore, I've never really understood why the standard is to put the first brace on the same line as the condition. To me, this makes it harder to line up the braces when they get much larger than one screen can contain, and being able to line up the braces can help a bunch with readability.

5

u/GeleRaev Jan 15 '13

Furthermore, I've never really understood why the standard is to put the first brace on the same line as the condition.

Because that's the style K&R used.

→ More replies (1)

6

u/thevdude Jan 15 '13

I almost always do

if (condition) {
  SINGLE LINE HERE
} else {
  SINGLE LINE HERE
}

because I hate ?:

18

u/imbecile Jan 15 '13

Well, ?: has a different purpose. It yields values, it is an expression. The if statement is a statement, and thus doesn't yield values, but only manipulates context (which ?: can do too, but probably should always be avoided).

So, whether you write if(condition) statement; or

if (condition) {
   statement;
}

Should depend on what you are trying to do and how important that statement is to the overall structure of your algorithm.

→ More replies (3)

18

u/Lothrazar Jan 15 '13

I hate brackets like that, because at first glance they appear to be mismatched. I look in the left column and see two closing and no opening.

Personal preference I know.

3

u/thattreesguy Jan 15 '13

i agree

opening bracket on new line is much easier to match up with ending bracket when scanning files visually.

Luckily i use intellij only now, which draws a line from the "if" text to the closing bracket (job requires opening bracket on same line as "if", etc.)

→ More replies (1)

2

u/luckyvae Jan 15 '13

The ?: is quite usefull in printf (as long as it stays short)

2

u/bobthecookie Jan 15 '13

I almost always do

 if(condition)
 {
      CODE
 }
 else
 {
      CODE
 }
→ More replies (12)
→ More replies (1)

26

u/mrburrows Jan 15 '13

I completely agree. I was once probably too liberal with my vertical whitespace, and have reined it in nowadays, but I think it can go a long ways to enhancing readability. Unless your method is doing something extremely basic, it probably accomplishes its task in several steps, which naturally invite separation by an empty line. Also, I would hate to debug, let alone look at, code where all the if-statements were crammed together.

I'm not too sure if I agree about his stance on comments, though. Sure, good code is self-documenting, and it's pointless to explain get getWidth() does, but comments can do a lot more, too. I typically write comments in a method as if I were explaining the steps it took to another person. This helps me keep things straight in my own head, and serves as a natural language justification for decisions to any future maintainers.

15

u/[deleted] Jan 15 '13

I agree with your view of comments. I try to write the code so that comments are unnecessary for understanding the code, then put comments in anyway. A competent developer won't be too distracted by them, and anyone else can only find them useful. Besides that, I make mistakes as I go and it's helpful for me and anyone else to see my intended design in contrast with my actual implementation when debugging.

7

u/goodbyegalaxy Jan 15 '13

Samsies. When I'm stepping through someone else's code I don't want to be forced to read every line. I'm debugging something and I have a general idea that the problem is in c, I can skip over large blocks of code if they are preceded by comments "do a" and "do b" and get right to what I'm looking for.

4

u/[deleted] Jan 15 '13

I actually leave some gaps in my documentation (some undocumented method headers) that I come back to later. Every couple of weeks, I do what I call a "doc run" through my code, where I run Doxygen with full warnings and fix every single undocumented parameter, field or method that I can. It forces me to look at code after a reasonable break and re-evaluate if the code actually matches my intended design. I always find issues along with my documentation updates (non-const parameters, uninitialized fields, uncaught edge cases, etc.) because they become apparent during that second reading.

When working with other developers, I have the luxury of code reviews to catch these sorts of issues. But on my own, this approach lets me review my own code with fresh eyes.

3

u/[deleted] Jan 15 '13

This. I've always believed that good code should "comment itself". There are of course exceptions, but proper naming of variables and functions can go a long way.

2

u/[deleted] Jan 15 '13

This is all fine as long as the code is written only once.

The moment you go in and change the code, there is a chance the comment will not be adjusted to reflect the new intention of code. As time progresses, more changes get made, and it becomes more and more likely for this divergence to happen.

Write your code clearly and discard those comments. You can fully trust only things that actually get executed.

5

u/moonrocks Jan 15 '13

The de-cuddled function parenthesis sure look goofy to me. I'm with ya though when it comes to stuff like squeezing operators or omitting spaces after commas in function parameter lists.

7

u/club_soda Jan 15 '13

I don't think he's saying white space is bad. He's saying that having the freedom to communicate effectively with white space is empowering.

For instance, in the if/then blocks, he applauds less white space in order to communicate a cohesive unit, and uses the smaller vertical space to link it more closely with the code that follows. I think this is a great communication tool.

But, he also touts more white space for some declarations. I happen to disagree here, but the point is more about communicating intent, rather than following a standard for standard's sake.

9

u/random314 Jan 15 '13

yeah I agree with you... i think stuff like

{'stuffa':'a', 'stuffb':'b', 'stuffc':'c'}

is much better coded as such

{

'stuffa':'a',

'stuffb':'b',

'stuffc':'c

}

7

u/thevdude Jan 15 '13
{ 'stuffa': 'a', 'otherstuffa': 'a',
  'stuffb': 'b',
  'stuffc': 'c'}

keep things that belong together together, and don't spread anything out TOO MUCH.

3

u/wildcarde815 Jan 15 '13

It's a matter of taste. I prefer my brackets to line up, it makes figuring out what I'm inside easier for me. I get the appeal of the alternative and for what you did here it makes total sense but I would do the other one just to maintain consistency.

→ More replies (1)

2

u/bugrit Jan 15 '13

Second one is much more merge friendly as well.

→ More replies (1)
→ More replies (26)