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.
The fact that it was written in assembly and then C makes a stronger implication that they had no class named CollisionDetector.
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 ;)
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.
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.
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.
# 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.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 packagethe problem starts when the 'why' doesn't match the 'how'...which one is "correct"?
I share the same experience.
// assign the integer value 10 to the variable x
x = 10 const TEN = 12; #define true false // set the variable x to 10
x = 12; sFile = "filename.xml";
then later sFile = File.ReadAllText("filename.xml");Still haven't figured out a reliable enough garble detection mechanism that my employer's willing to pay for.
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!)
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!
Just... garbage attitude oozing through the code at every line - difficult to work with.
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.
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
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.
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.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.
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?
This game was another casualty of maximizing value towards shareholders and away from all other stakeholders.
What if dropping Pinball was not an option? The cost to the shareholder would have been much higher than it needed to be.
^That might have helped a little.
... 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.