News for hackers. Stuff that matters.
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.