4 ms·

I came here to say exactly the opposite. I read a lot of code these days where people seem to think that descriptive variable and function names replace the ne

I came here to say exactly the opposite. I read a lot of code these days where people seem to think that descriptive variable and function names replace the need for any comments. But, even the most well written code is only going to make it clear _what_ the code it doing. The _why_ is likely to remain obscure. And without knowing why the code does what it does, it will often be impossible to know whether you can make certain changes.

azanar 17y ago
The _why_ is likely to remain obscure. The why might remain obscure, but that depends on two very important things: your documentation, as you noted; and your data structures. Show me your flow charts and conceal your tables and I shall continue to be mystified, show me your tables and I won't usually need your flow charts; they'll be obvious. - Fred Brooks As much as you can organize your data to make the purpose of it obvious, do that. It will make the system far easier for a new-comer to comprehend, and will make far more obvious to do you the sort of code you need to write to make the wheels turn. Where that is not enough, then use comments, but don't assume that prose is an adequate replacement for precise and logical data representation. Often times, I've found that the latter is a far better choice.
- tetha 17y ago
  This is the reason why I am kind of laughed at, and why my comments are kind of feared, because I either don't need comments at all, but once I need comments, they usually end up being a page of things you need to know about this unit.
gruseom 17y ago
You make a good point about why vs. what. Still, my experience has been that if I ask myself when adding a comment, "Could I make the code say this instead?" the answer is "yes" 9 times out of 10. It is preferable to do so because code is much likelier to be read and maintained than comments are. Also, this question often makes me see flaws in how the code was expressing itself, so I end up with better code.
- Retric 17y ago
  I think the best comment is one which explains an ugly edge case which forces the code to look like it does. //window.update; is not used because of API bug #12345 see: bugs.mysql.com/12345 so use xyz instead. Nine times out of ten I can read and understand good code with little effort, but code often starts out looking clean and becomes messy for a reason.

azanar 17y ago

The _why_ is likely to remain obscure. The why might remain obscure, but that depends on two very important things: your documentation, as you noted; and your data structures. Show me your flow charts and conceal your tables and I shall continue to be mystified, show me your tables and I won't usually need your flow charts; they'll be obvious. - Fred Brooks As much as you can organize your data to make the purpose of it obvious, do that. It will make the system far easier for a new-comer to comprehend, and will make far more obvious to do you the sort of code you need to write to make the wheels turn. Where that is not enough, then use comments, but don't assume that prose is an adequate replacement for precise and logical data representation. Often times, I've found that the latter is a far better choice.

tetha 17y ago
This is the reason why I am kind of laughed at, and why my comments are kind of feared, because I either don't need comments at all, but once I need comments, they usually end up being a page of things you need to know about this unit.

gruseom 17y ago

You make a good point about why vs. what. Still, my experience has been that if I ask myself when adding a comment, "Could I make the code say this instead?" the answer is "yes" 9 times out of 10. It is preferable to do so because code is much likelier to be read and maintained than comments are. Also, this question often makes me see flaws in how the code was expressing itself, so I end up with better code.

Retric 17y ago
I think the best comment is one which explains an ugly edge case which forces the code to look like it does. //window.update; is not used because of API bug #12345 see: bugs.mysql.com/12345 so use xyz instead. Nine times out of ten I can read and understand good code with little effort, but code often starts out looking clean and becomes messy for a reason.