Post Made Community Wiki by GlenPeterson
3 Added example outside of coding to further argue the need for comments
source | link

I think the topic is well chosen. It's "cool" to write a line of Perl that does ten thousand things all at once, but then it sucks when you have to revisit it.

On a different note, clever or not, code must be documented. There is an inherent impedance mismatch between the industry-accepted programming languages and the high level concepts that we as humans are accustomed to in our thinking. Self-documenting code is simply not realizable - until it becomes natural language, that is. Even Prolog code needs to be documented, as, however high level it may be, it is still rather formal.

Fine grained imperative code serves to implement coarse grained plans -- that needs to be documented. I don't want to have to read through all 50 lines of the method when a quick 3-line roadmap comment will do.

Later edit: A more eloquent example is one that transcends computers. A book may be very well written, but we often want to process it at different levels of abstraction. Often, a summary of the book will do, and that's what comments can offer to code. Of course well abstracted code can go a long way towards self documentation, but it can't give you all the levels of abstraction.

And comments can also act just like sidenotes in a book a sidenote is sometimes needed, when we need to explain the reasoning process behind a conclusion without derailingclaim in the main text without derailing it.

InWith this context, the statementI find that my prior to the editstatement referring to natural language transcending the need for comments is inexactincorrect. Even natural language, like in a book, may lend itself to documentation, to explain in a sparse manner the abstraction embodied byin the codetext, or to provide detours without derailing the main text. With the note that well abstracted code may already have gone a long way towards being self documenting.

Last, but not least, comments can help the coder keep at a high level of abstraction. Often times I realize that two consecutive comments I included in a list of steps don't speak at the same level of abstraction, which immediately warrants a critical look at what I'm doing with that code.

Certain problems transcend coding and affect coding just like other activities. Comments can provide that help in clarifying rationalesthe rationale behind, and facets of our code, and I find them a pleasant companion that speaks a softer language to benefit the person for a change.

I think the topic is well chosen. It's "cool" to write a line of Perl that does ten thousand things all at once, but then it sucks when you have to revisit it.

On a different note, clever or not, code must be documented. There is an inherent impedance mismatch between the industry-accepted programming languages and the high level concepts that we as humans are accustomed to in our thinking. Self-documenting code is simply not realizable - until it becomes natural language, that is. Even Prolog code needs to be documented, as, however high level it may be, it is still rather formal.

Fine grained imperative code serves to implement coarse grained plans -- that needs to be documented. I don't want to have to read through all 50 lines of the method when a quick 3-line roadmap comment will do.

Later edit: A more eloquent example is one that transcends computers. A book may be very well written, but we often want to process it at different levels of abstraction. Often, a summary of the book will do, and that's what comments can offer to code. Of course well abstracted code can go a long way towards self documentation, but it can't give you all the levels of abstraction.

And comments can also act just like in a book a sidenote is sometimes needed to explain the reasoning process behind a conclusion without derailing the main text.

In this context, the statement prior to the edit referring to natural language is inexact. Even natural language, like in a book, may lend itself to documentation, to explain in a sparse manner the abstraction embodied by the code. With the note that well abstracted code may already have gone a long way towards being self documenting.

Certain problems transcend coding and affect coding just like other activities. Comments can provide that help in clarifying rationales behind, and facets of our code.

I think the topic is well chosen. It's "cool" to write a line of Perl that does ten thousand things all at once, but then it sucks when you have to revisit it.

On a different note, clever or not, code must be documented. There is an inherent impedance mismatch between the industry-accepted programming languages and the high level concepts that we as humans are accustomed to in our thinking. Self-documenting code is simply not realizable - until it becomes natural language, that is. Even Prolog code needs to be documented, as, however high level it may be, it is still rather formal.

Fine grained imperative code serves to implement coarse grained plans -- that needs to be documented. I don't want to have to read through all 50 lines of the method when a quick 3-line roadmap comment will do.

Later edit: A more eloquent example is one that transcends computers. A book may be very well written, but we often want to process it at different levels of abstraction. Often, a summary of the book will do, and that's what comments can offer to code. Of course well abstracted code can go a long way towards self documentation, but it can't give you all the levels of abstraction.

And comments can also act like sidenotes in a book, when we need to explain the reasoning process behind a claim in the main text without derailing it.

With this context, I find that my prior statement referring to natural language transcending the need for comments is incorrect. Even natural language, like in a book, may lend itself to documentation, to explain in a sparse manner the abstraction embodied in the text, or to provide detours without derailing the main text. With the note that well abstracted code may already have gone a long way towards being self documenting.

Last, but not least, comments can help the coder keep at a high level of abstraction. Often times I realize that two consecutive comments I included in a list of steps don't speak at the same level of abstraction, which immediately warrants a critical look at what I'm doing with that code.

Certain problems transcend coding and affect coding just like other activities. Comments can provide that help in clarifying the rationale behind, and facets of our code, and I find them a pleasant companion that speaks a softer language to benefit the person for a change.

2 Added example outside of coding to further argue the need for comments
source | link

I think the topic is well chosen. It's "cool" to write a line of Perl that does ten thousand things all at once, but then it sucks when you have to revisit it.

On a different note, clever or not, code must be documented. There is an inherent impedance mismatch between the industry-accepted programming languages and the high level concepts that we as humans are accustomed to in our thinking. Self-documenting code is simply bull shitnot realizable - until it becomes natural language, that is. Even Prolog code needs to be documented, as, however high level it may be, it is still rather formal.

Fine grained imperative code serves to implement coarse grained plans -- that needs to be documented. I don't want to have to read through all 50 lines of the method when a quick 3-line roadmap comment will do.

Later edit: A more eloquent example is one that transcends computers. A book may be very well written, but we often want to process it at different levels of abstraction. Often, a summary of the book will do, and that's what comments can offer to code. Of course well abstracted code can go a long way towards self documentation, but it can't give you all the levels of abstraction.

And comments can also act just like in a book a sidenote is sometimes needed to explain the reasoning process behind a conclusion without derailing the main text.

In this context, the statement prior to the edit referring to natural language is inexact. Even natural language, like in a book, may lend itself to documentation, to explain in a sparse manner the abstraction embodied by the code. With the note that well abstracted code may already have gone a long way towards being self documenting.

Certain problems transcend coding and affect coding just like other activities. Comments can provide that help in clarifying rationales behind, and facets of our code.

I think the topic is well chosen. It's "cool" to write a line of Perl that does ten thousand things all at once, but then it sucks when you have to revisit it.

On a different note, clever or not, code must be documented. There is an inherent impedance mismatch between the industry-accepted programming languages and the high level concepts that we as humans are accustomed to in our thinking. Self-documenting code is simply bull shit - until it becomes natural language, that is. Even Prolog code needs to be documented, as, however high level it may be, it is still rather formal.

Fine grained imperative code serves to implement coarse grained plans -- that needs to be documented. I don't want to have to read through all 50 lines of the method when a quick 3-line roadmap comment will do.

I think the topic is well chosen. It's "cool" to write a line of Perl that does ten thousand things all at once, but then it sucks when you have to revisit it.

On a different note, clever or not, code must be documented. There is an inherent impedance mismatch between the industry-accepted programming languages and the high level concepts that we as humans are accustomed to in our thinking. Self-documenting code is simply not realizable - until it becomes natural language, that is. Even Prolog code needs to be documented, as, however high level it may be, it is still rather formal.

Fine grained imperative code serves to implement coarse grained plans -- that needs to be documented. I don't want to have to read through all 50 lines of the method when a quick 3-line roadmap comment will do.

Later edit: A more eloquent example is one that transcends computers. A book may be very well written, but we often want to process it at different levels of abstraction. Often, a summary of the book will do, and that's what comments can offer to code. Of course well abstracted code can go a long way towards self documentation, but it can't give you all the levels of abstraction.

And comments can also act just like in a book a sidenote is sometimes needed to explain the reasoning process behind a conclusion without derailing the main text.

In this context, the statement prior to the edit referring to natural language is inexact. Even natural language, like in a book, may lend itself to documentation, to explain in a sparse manner the abstraction embodied by the code. With the note that well abstracted code may already have gone a long way towards being self documenting.

Certain problems transcend coding and affect coding just like other activities. Comments can provide that help in clarifying rationales behind, and facets of our code.

1
source | link

I think the topic is well chosen. It's "cool" to write a line of Perl that does ten thousand things all at once, but then it sucks when you have to revisit it.

On a different note, clever or not, code must be documented. There is an inherent impedance mismatch between the industry-accepted programming languages and the high level concepts that we as humans are accustomed to in our thinking. Self-documenting code is simply bull shit - until it becomes natural language, that is. Even Prolog code needs to be documented, as, however high level it may be, it is still rather formal.

Fine grained imperative code serves to implement coarse grained plans -- that needs to be documented. I don't want to have to read through all 50 lines of the method when a quick 3-line roadmap comment will do.