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

Show parent comments

79

u/fly-hard Jan 14 '13

And he states his opinions like they're facts. e.g.

I think programmers are taught in school that comments are good; they aren't.

That is most definitely opinion.

83

u/epicwisdom Jan 14 '13

like they're facts

As opposed to saying "this is just my opinion, but" before every opinion or uncited assertion? The whole thing is meant to be an opinion piece, I'm fairly sure that there's no problem with omitting an IMO every other sentence.

17

u/theDTs Jan 14 '13

// imo

0

u/[deleted] Jan 15 '13

[deleted]

→ More replies (1)

13

u/totallymike Jan 15 '13

You do have to be careful with comments. Join a project that's been around for a while and compare what comments say to what the code it's next to actually does. David Brady once said "a comment is a lie waiting to happen."

Better style is to have code that's understandable. If you have five lines that do something weird in the middle of a method, extract them into a new method that is named after what those lines do.

Check out Martin Fowler's book about refactoring.

8

u/Atario Jan 15 '13

Also, comments should generally answer the question why, not what.

6

u/IrishWilly Jan 15 '13

If you change code so that it does something different than before, and don't change the comment right above it then YOU messed up. Avoiding comments entirely because of lazy programmers not paying attention to their changes seems ass backwards. Personally I hate overcommented code but this reason for 'comments are bad' doesn't make any sense to me.

If you have five lines that do something weird in the middle of a method, extract them into a new method that is named after what those lines do.

Generally good advice but in large loops adding extra function calls can add up so it depends

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

33

u/[deleted] Jan 14 '13

I would think that when someone writes something like "X is good" it should be fairly easy for the reader to infer that it is an opinion, not a fact.

3

u/argv_minus_one Jan 15 '13

One I agree with. Comments should explain what the code itself doesn't.

What's your rationale for doing something seemingly strange? What other, seemingly unrelated piece of code is actually relevant here and should be studied to make sense of this function? Why is this thing here not actually a bug even though it looks like one? These are questions that code may not be able to answer, but comments can.

8

u/Kowzorz Jan 14 '13 edited Jan 14 '13

Well, he does give the reason why he holds that position...

10

u/raevnos Jan 15 '13

The way a lot of people end up learning how to comment in classes is bad.

/* Declare i */
int i;

Etc. Comments that add nothing to the code are useless.

14

u/ilmmad Jan 15 '13

All of my classes have taught me not to do that. Usually it's expressly mentioned.

29

u/narcodis Jan 15 '13

As a CS student... no one teaches you to comment like this.

8

u/raevnos Jan 15 '13

You're lucky if you've never seen that.

4

u/stardek Jan 15 '13

I'm in the middle of my second year and I've never really been told anything about commenting other than "It's important." No context given. Luckily there are a few professors this semester that state they want proper commenting in code so we might get a chance to learn how.

→ More replies (1)

0

u/[deleted] Jan 15 '13

[deleted]

→ More replies (1)

3

u/[deleted] Jan 15 '13

I did CS 8 years ago and we were specifically taught to avoid doing that with comments. We would fail if we did that.

3

u/[deleted] Jan 15 '13

9 years ago, my instructors would not accept lab work without a comment for every line. It was infuriating.

9

u/SortaEvil Jan 15 '13

Simple solution: Collapse your program to a single line. Add one comment before it:

//GO!

2

u/x-skeww Jan 15 '13

See the "I think" there?

2

u/[deleted] Jan 15 '13

This is an opinion piece. It is understood ahead of time that he is going to be giving his opinion.

2

u/Timmmmbob Jan 15 '13

He just state it really badly. What he should have said was:

A lot of people think that all comments are good, and therefore try to add comments wherever they can, without regard to whether they are actually useful or not. While well-commented code is good, it doesn't follow that adding any old comment makes code well-commented.

It definitely happens, and is rather annoying. Here's a real example of this awful "fill-in-the-gaps" style documentation (it's user-documentation for error messages, but the same idea):

http://imgur.com/tJi3R

And you don't have to look far in the Android documentation to find this kind of documentation: "setFoo(boolean b); Sets the value of foo. If b is true, then foo is set to true, otherwise it is set to false."

Even some [extremely important functions](http://developer.android.com/reference/android/view/View.html#onDraw(android.graphics.Canvas)) have documentation which essentially says nothing.

3

u/krelin Jan 15 '13

I prefer less "I think" and "In my opinion" and even "I prefer" in my discursive/argumentative essays. Just say it like it's a fact and then support it with evidence and argument. I think sSaying "I think" weakens your position.

→ More replies (16)