Hacker News Reader

Comment by randomdrake | Hacker News Reader

This is an excellent example of why comments in code are so very useful, helpful and in my opinion, necessary.

... nobody at Microsoft ever understood how the code worked (much less still understood it), and that most of the code was completely uncommented, we simply couldn't figure out why the collision detector was not working. Heck, we couldn't even find the collision detector!

To all those folks out there who keep finding reasons to try and be clever with their language, or omit comments from their code: now you can remember Pinball. It's very possible that with some minimal commenting about what functions did, or what the intentions of block of codes were, Pinball could have lived on. Heck, we could have even seen a Modern UI version of Pinball.

View on HN

There are some readability problems that stem from a lack of comments, and there are other readability problems that stem from exceedingly poorly-written code.

Heck, we couldn't even find the collision detector!

This sentence tells me that the big problem here comes from the latter, much worse, source of of readability problems. The fact that they couldn't find the collision detector implies that the code had no class named CollisionDetector, no procedure named DetectCollisions, nothing of the sort. Which implies (if not conclusively) that there was a whole lot spaghetti code floating around in there. Or at least a whole lot of very poorly-factored code.

I do think that comments are an important part of making code readable and maintainable. But comments are there to handle less drastic readability concerns. Documenting what units a parameter should be in, for example, or saying, "The following code implements X algorithm with Y and Z optimizations applied." Comments should never just be a substitute for using language-level code organizational and structuring constructs to organize and structure one's code.

To me that fragment says that the story is a bit more colourful than what really happened. This quote comes from Raymond Chen. The guy who includes ISA bus, interrupts and starting up a debugger in one post (http://blogs.msdn.com/b/oldnewthing/archive/2007/01/30/15574...); or analysing chip issues and software workarounds for them (http://blogs.msdn.com/b/oldnewthing/archive/2011/01/12/10114...).

Maybe the code was really messy and hard to work with... but it's hard to believe that he couldn't find the collision detector ;)

A programmer from the original game commented on the article and said much of it was done in asm then later ported to C by msft, so it probably was really that messy.

This smells like automatically generated procedure names based on dataflow analysis.

The fact that they couldn't find the collision detector implies that the code had no class named CollisionDetector

The fact that it was written in assembly and then C makes a stronger implication that they had no class named CollisionDetector.

I'm pretty sure I saw a library somewhere that could be purchased in both "raw code" and "commented, documented code" forms.

Which I can only assume meant they had the comments/documents and were intentionally stripping them out for the cheaper version. The difference in price was also actually quite significant as well, as I recall.

That, along with the fact that the person doing the purchasing is not necessarily the person who would be using the product, makes this IMO a particularly nasty sales tactic.

I've also heard war stories from Big Company folks about contracting out for a large software project, and per contract receiving the full source for the app, but none of the (particularly convoluted) build scripts or Makefiles.

Lessons Learned are why BigCo has a 900 page specification document including glossary of what the word "means" means.

This is also a great example of what happens during acquisitions.

Space Cadet was developed by Cinematronics (apparently no connection to the classic arcade game manufacturer) and published by Maxis. Maxis eventually bought Cinematronics. Then (according to Wikipedia) "The studio was closed and the employees were laid off when Maxis was acquired by Electronic Arts in 1997."

So someone out there knows how to fix it. I bet Microsoft called EA looking for a quick/free fix, EA called the employee (or lost track of them, more likely), and the employee told them to stick it.

It's an argument for clear code that's readily understandable by other people. It's not an argument for any particular technique for achieving that goal. I've never seen any programmer seriously suggest that code should be deliberately made difficult to understand.

"I've never seen any programmer seriously suggest that code should be deliberately made difficult to understand."

Then you've not worked with some of the people I've worked with. The clever "it was hard to write, it should be hard to read" mantra has been thrown out by a few ex-colleagues trying to be clever, and a couple of them really meant it. Whether it was a hatred for others, or a misguided attempt at "job security", I'll never know, but some of these people do exist.

Often, however, the same effect is had under the guise of "clever hacks" - look how clever and awesome I am! What? Of course everyone else can read and understand this (they just have to understand that I compiled this with my own custom-built compiler I rolled myself on gentoo so I could squeeze out an extra .0001% improvement!)

Maybe some awful programmers do advocate for it, but that doesn't really change my overall point. There is no serious argument in the community, at least, over whether code should be readable. The argument is merely about how to make it readable, and this story does not argue for any particular approach there.

One guy I worked with would do it to protect his bailiwick. He was intensely territorial, and knew that writing code so ugly that nobody wanted to even look at it, much less take the time to understand it, was an effective way to make sure that nobody else on the team would ever touch anything he wrote.

Sounds like "mortgage code"... code that is intentionally so complex that noone in the company other than yourself can maintain it, hence you end up with a job for life that pays your mortgage.

Ha. Unfortunately for him, it became clear that most of his code was all sound and fury, calculating nothing. Well, that and he took forever to fix bugs because he couldn't really understand it either.

He was soon out on the street, and the rest of the team's policy of just rewriting bits instead of debugging them (it never took very long, and frequently resulted in 1/10 as many lines of code doing twice as much) had soon swept away most of his footprints.

"Often, however, the same effect is had under the guise of "clever hacks" - look how clever and awesome I am!"

Sometimes I write code like that. Then I delete it and write it the proper way.

Clever code is code you will not be able to understand in the morning.

There is Kernighan's adage

"Debugging is twice as hard as writing the code in the first place. Therefore, if you write the code as cleverly as possible, you are, by definition, not smart enough to debug it."

Indeed I fear I wrote code like that yesterday (a particular problem that, after talking to 3 other engineers, everyone agreed did not have a simple solution) that I am going to have to debug today. I am not looking forward to it!

useful thoughts. it reinforces my view that it's really the intent that bugs me. I've dealt with crap code, littered with comments like "I'm sorry, didn't know what I was doing, etc". The person/people knew they were in a tough spot. In other cases I've dealt with crap code with random comments like "Java sucks. Sun sucks. Everyone using Java sucks and is stupid - Ruby is the only true language, and it sucks that this is in Java" and "if you're too stupid to understand this, quit right now and tell so-and-so to go hire a real programmer".

Just... garbage attitude oozing through the code at every line - difficult to work with.

This ranting was in a professional environment, or some kind of open source project..?

"professional" env.

yeah, +1. In this religious war, I side with "if anyone who has a reasonable level of competence with my code can't grasp it at first reach, I have failed in writing it."

Or, famously, "Debugging is twice as hard as writing the code in the first place. Therefore, if you write the code as cleverly as possible, you are, by definition, not smart enough to debug it." --Brian Kernighan

Respectfully, commenting code and making it easily readable don't usually add to the bottom line. So while we all miss playing Pinball, it would be a waste of money to the shareholders.

This game was another casualty of maximizing value towards shareholders and away from all other stakeholders.

I disagree. Sure, in the short term, taking on that technical debt may have made sense, but in the long term, this is a perfect example of how technical debt added significant maintenance costs to a project.

What if dropping Pinball was not an option? The cost to the shareholder would have been much higher than it needed to be.

I would suspect the programmer was lazy or rushed, and wasn't considering shareholder value.

Rushed is really the same thing, even if the words "shareholder value" weren't in their minds at the time.

There's some commonly repeated (and likely even true to some extent) that ~60-70% of the cost of a software system is in maintenance. Which to me, sounds like if you're the contractor providing the system, that means 60-70% of the value is in the maintenance. It does mean taking something of a hit upfront so make things maintainable, but with the right billing structure you can be adding to the profits by Doing It Right as you go. It's certainly still a gamble though; you might not get the maintenance contract. You might be billing hourly and thus don't see any extra cash for your timesavings (and indeed, might see less).

I can't agree with you emphatically enough about this. Cargo cult commenting is one of the easiest ways to damage the readability of a codebase.

Comments should be an edge-case solution for explaining unusual quirks, not the go-to approach for explaining the entire codebase. Using comments to explain what the code is up to is like using exceptions for flow of control. A large proportion of the comments I see should actually be function or method names for a more well factored version of the block of code that follows.

I agree that comments should not be the "go-to approach for explaining the entire codebase." I hope you didn't think I was insinuating that in my comment. I was only trying to illustrate that in the absence of clear code, which many developers are guilty of sometimes, comments can be very helpful.

Nah I didn't think that at all, it was clear from the way you said "minimal commenting". I just have an axe to grind when it comes to comments of the form

    // assign the integer value 10 to the variable x
    x = 10

What's really annoying is that most of the time you see this kind of comment there is no explanation why 10 was chosen.

And that's what comments really need to do: tell 'why.'

http://xkcd.com/221/

That's why you should use constants. Still self documenting without the need for comments (usually).

    const TEN = 12;

    #define true false

In our embedded systems class we were required to define all of our constants, just to add another level of description to operations. It definitely helped to navigate spaghetti code.

At least it's better than:

    // set the variable x to 10
    x = 12;

  sFile = "filename.xml";

then later

  sFile = File.ReadAllText("filename.xml");

I think you've forgotten a leading zero ;)

Sadly, I fear that comments won't help in that situation. They could, except that the solution depends critically on the developer realizing they're writing garbled code during the time they're writing it. I don't know about anyone else, but my code's never garbled when I write it. It only becomes garbled by magic, and only when I don't look at it for a few weeks. Or, strangely enough, the moment someone else looks at it.

Still haven't figured out a reliable enough garble detection mechanism that my employer's willing to pay for.

"A large proportion of the comments I see should actually be function or method names for a more well factored version of the block of code that follows."

I share the same experience.

This point gets brought up a lot, but I'm not going to complain at all. In fact, just 5-6 months ago I used to be one of those programmers who would do

    # gets the xml
    def get_xml():

It took comments like this to help me realize just how silly the whole thing was. Now I write as much self-documenting code as I can, but comment as needed.

Sure.

Comment should be "why I did this", and code should be "how I did this", some people just write in "what did I do" and walk away thought they have comment

Code took from a project I'm working with:

  #End of package

I generally become aware that I should leave a comment whenever I write something that is less than trivial (but exactly less than trivial) to write/understand. Longish list comprehension? Summarize what it does. Nested function calls? Summarize why. Etc.

> Comment should be "why I did this", and code should be "how I did this"

the problem starts when the 'why' doesn't match the 'how'...which one is "correct"?

This may be a valid argument for modern languages like Ruby or Python. For 90s' coding standards however comments are even MORE important than the code itself. For Assembly and C programming and for low level graphics and physics algorithms proper naming of variables and functions are never enough for readable code.

I haven't heard the argument about making code deliberately hard to understand either.

I agree that clearer code and/or commenting would have been suitable.

I only latched on to the example because they specifically mentioned that the code wasn't commented. In this case, a few lines of comments might have helped them find what they were looking for. Even if they original programmer was one of those people who just can't stop writing code like:

  $a = ($b)?($ab):$c;
  d($a);

Maybe some amount of convincing could lead them to leave a comment every once in a while so we can at least get:

  // Detect collision
  $a = ($b)?($ab):$c;
  d($a);

Since it seems like both clear code and comments were absent, either one would have been helpful.

I don't think comments are any kind of substitute for clear, well-structured code. In your example, "Detect collision" still doesn't give me any kind of epiphany about the code. At best, it gives me a slight hint about where to go to get more information. Chances are I'm trying to fix a bug or change the behavior, so I still need to figure what $a, $b, $ab, $c, and d are and what their purpose is.

In other words, I have nothing against good comments, especially on obscure code, but I think they're only marginally useful even in those cases.

Definitely. I wasn't trying to say that they were a substitute. I specifically said both could have worked. In the example they cited, they couldn't even find where to begin. A small comment could have done something about it.

When you can't have both clear code and commenting, you could at least try to do one every once in a while. How can that be a bad thing?

What other technique do you have at your disposal in a code originally written in assembly and then translated to C, and then refactored several times without rewrite?

I personally didn't hear of one that would be usable in this case.

Also, I'm starting to think I should write a script to cut out every comment here that has "code" and "comments" in it - among with several other phrases that signify neverending debates.

This is an excellent example of why comments and well documented code should be part of the licensing agreement.

Comments under the article seem to imply that most of the relevant code was somehow hand converted from (probably well commented) assembly to C which I only assume was done by someone who had no interest in how or why the code actually works, which seems to perfectly explain the lack of comments (or meaningful structure for that matter).

There is no reason not to "be clever with your language", as long as you separate the "cleverness" behind a clear interface.

If they weren't able to find the collision detector, I seriously doubt the comments would've been of a usable quality.

//Collision detector logic starts here

^That might have helped a little.

You don't understand. The kind of person who writes an undetectable collision detector will never write a comment like this. He might write some other comment, but it will be as obscure as his code.

I read that comment and immediately thought of this HN post and why i disagreed with everything in that article.

http://news.ycombinator.com/item?id=4934417

I usually argue that version control history is often as useful as code comments. In this case, though, I suppose comments would have been better than some arcane 15 year old VCS :)

Reply on news.ycombinator.com