News for hackers. Stuff that matters.
Re:Why was Pinball removed from Windows Vista? by mikeash on Tuesday December 18, 2012 @01:16PM (#4938719)
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.
Re:Why was Pinball removed from Windows Vista? by h2s on Tuesday December 18, 2012 @01:57PM (#4938914)
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.

Re:Why was Pinball removed from Windows Vista? by RegEx on Tuesday December 18, 2012 @04:48PM (#4939779)
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.
Re:Why was Pinball removed from Windows Vista? by Funnnny on Wednesday December 19, 2012 @05:22AM (#4941971)
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
Re:Why was Pinball removed from Windows Vista? by StavrosK on Wednesday December 19, 2012 @06:38AM (#4942144)
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.
Re:Why was Pinball removed from Windows Vista? by chii on Wednesday December 19, 2012 @08:57AM (#4942556)
> 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"?

Re:Why was Pinball removed from Windows Vista? by mjbellantoni on Tuesday December 18, 2012 @04:08PM (#4939599)
"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.

Re:Why was Pinball removed from Windows Vista? by ozgung on Wednesday December 19, 2012 @07:31AM (#4942274)
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.
Re:Why was Pinball removed from Windows Vista? by randomdrake on Tuesday December 18, 2012 @03:21PM (#4939383)
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.
Re:Why was Pinball removed from Windows Vista? by h2s on Tuesday December 18, 2012 @03:44PM (#4939486)
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
Re:Why was Pinball removed from Windows Vista? by miahi on Tuesday December 18, 2012 @04:06PM (#4939581)
What's really annoying is that most of the time you see this kind of comment there is no explanation why 10 was chosen.
Re:Why was Pinball removed from Windows Vista? by dhimes on Tuesday December 18, 2012 @04:55PM (#4939816)
And that's what comments really need to do: tell 'why.'
Re:Why was Pinball removed from Windows Vista? by Pyrodogg on Tuesday December 18, 2012 @05:41PM (#4940037)
Re:Why was Pinball removed from Windows Vista? by MetallicCloud on Tuesday December 18, 2012 @07:24PM (#4940535)
That's why you should use constants. Still self documenting without the need for comments (usually).
Re:Why was Pinball removed from Windows Vista? by adamzegelin on Tuesday December 18, 2012 @10:16PM (#4940969)

    const TEN = 12;
Re:Why was Pinball removed from Windows Vista? by tehwalrus on Wednesday December 19, 2012 @05:10AM (#4941939)

    #define true false
Re:Why was Pinball removed from Windows Vista? by fudged71 on Thursday December 20, 2012 @03:19AM (#4946746)
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.
Re:Why was Pinball removed from Windows Vista? by mikeash on Tuesday December 18, 2012 @04:18PM (#4939645)
At least it's better than:

    // set the variable x to 10
    x = 12;
Re:Why was Pinball removed from Windows Vista? by sixothree on Tuesday December 18, 2012 @04:41PM (#4939747)

  sFile = "filename.xml";
then later

  sFile = File.ReadAllText("filename.xml");
Re:Why was Pinball removed from Windows Vista? by zvrba on Wednesday December 19, 2012 @03:00AM (#4941632)
I think you've forgotten a leading zero ;)
Re:Why was Pinball removed from Windows Vista? by bunderbunder on Tuesday December 18, 2012 @04:01PM (#4939558)
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.

Re:Why was Pinball removed from Windows Vista? by mgkimsal on Tuesday December 18, 2012 @01:23PM (#4938750)
"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!)

Re:Why was Pinball removed from Windows Vista? by com2kid on Tuesday December 18, 2012 @04:26PM (#4939686)
"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!

Re:Why was Pinball removed from Windows Vista? by mgkimsal on Tuesday December 18, 2012 @04:32PM (#4939702)
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.

Re:Why was Pinball removed from Windows Vista? by goostavos on Wednesday December 19, 2012 @01:04AM (#4941401)
This ranting was in a professional environment, or some kind of open source project..?
Re:Why was Pinball removed from Windows Vista? by mgkimsal on Wednesday December 19, 2012 @07:33AM (#4942279)
"professional" env.
Re:Why was Pinball removed from Windows Vista? by bunderbunder on Tuesday December 18, 2012 @01:58PM (#4938919)
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.
Re:Why was Pinball removed from Windows Vista? by damian2000 on Tuesday December 18, 2012 @09:37PM (#4940875)
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.
Re:Why was Pinball removed from Windows Vista? by bunderbunder on Wednesday December 19, 2012 @10:46AM (#4943055)
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.

Re:Why was Pinball removed from Windows Vista? by mikeash on Tuesday December 18, 2012 @01:47PM (#4938851)
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.
Re:Why was Pinball removed from Windows Vista? by hoka on Tuesday December 18, 2012 @01:23PM (#4938751)
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

Re:Why was Pinball removed from Windows Vista? by klibertp on Tuesday December 18, 2012 @03:43PM (#4939482)
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.

Re:Why was Pinball removed from Windows Vista? by randomdrake on Tuesday December 18, 2012 @03:05PM (#4939296)
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.
Re:Why was Pinball removed from Windows Vista? by jrajav on Tuesday December 18, 2012 @03:17PM (#4939358)
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.

Re:Why was Pinball removed from Windows Vista? by randomdrake on Tuesday December 18, 2012 @03:18PM (#4939367)
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?

Re:Why was Pinball removed from Windows Vista? by stephengillie on Tuesday December 18, 2012 @01:25PM (#4938756)
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.

Re:Why was Pinball removed from Windows Vista? by jsaxton86 on Tuesday December 18, 2012 @01:33PM (#4938791)
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.

Re:Why was Pinball removed from Windows Vista? by shabble on Tuesday December 18, 2012 @06:45PM (#4940353)
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).
Re:Why was Pinball removed from Windows Vista? by NoPiece on Tuesday December 18, 2012 @01:57PM (#4938911)
I would suspect the programmer was lazy or rushed, and wasn't considering shareholder value.
Re:Why was Pinball removed from Windows Vista? by corin_ on Tuesday December 18, 2012 @04:15PM (#4939625)
Rushed is really the same thing, even if the words "shareholder value" weren't in their minds at the time.