Hacker News new | past | comments | ask | show | jobs | submit login

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.



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.


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


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 ;)


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.'



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.




Join us for AI Startup School this June 16-17 in San Francisco!

Guidelines | FAQ | Lists | API | Security | Legal | Apply to YC | Contact

Search: