At the other extreme end of the spectrum is Donald Knuth's Literate Programming.
Where the code is embedded the equivalent of a giant comment (i.e., the documentation, requirements, specification, acceptance criteria, and other explanatory prose). Since this is from Donald Knuth, I rather expect that the document itself is in TeX.
I never worked with Literate Programming, but a co-worker of mine did extensively. Raymond Chen was a graduate student under Donald Knuth, and he got to experience Literate Programming personally for non-trivial projects.
Raymond's assessment was that the tooling for that style of programming was so poor, that it was practically unworkable.
He wasn't knocking Literate Programming; he was referring to the toolchains and debugging tools made it unbearable. That can be solved by better tools.
For me, good comments are useful, and are welcome. Bad comments are not useful, and I delete them.
A good comment explains WHY something is the way it is, HOW TO overview, or is a TODO.
A bad comment adds no value.
Because it is repeating what the code is doing, x = x + 1; // Increment x by one..
Or because the comment is incorrect, document.save(); // Load the document
Or because it could be made unnecessary by writing better code. int x = 0; // x is the person's age. --> int age = 0;
Or because the comments are scaffolding for when creating the code. Including pseudo-code. Once the code is created, the pseudo-code and "mini TODO" comments become unnecessary. And over time, the code will evolve making those comments incorrect. (My C++ project is 32 years old. There are a lot of those kinds of misleading comments.)
I think those kind of bad comments we can all agree are not useful. And, unfortunately, these are not contrived strawman examples.
Now if I was programming in Glass, I'd probably have a different take on comments. But I'll wait for Microsoft IronGlass#.NET before worrying about it. ;-)
Thanks Eljay-Adobe. Excellent discussion. Another thing I came across recently is the use of TODO comments. Apparently it is somewhat of a software security risk. We got flagged for that at work, although just LOW priority. To resolve them, just make sure to implement the code and remove the comment.
For further actions, you may consider blocking this person and/or reporting abuse
We're a place where coders share, stay up-to-date and grow their careers.
At the other extreme end of the spectrum is Donald Knuth's Literate Programming.
Where the code is embedded the equivalent of a giant comment (i.e., the documentation, requirements, specification, acceptance criteria, and other explanatory prose). Since this is from Donald Knuth, I rather expect that the document itself is in TeX.
I never worked with Literate Programming, but a co-worker of mine did extensively. Raymond Chen was a graduate student under Donald Knuth, and he got to experience Literate Programming personally for non-trivial projects.
Raymond's assessment was that the tooling for that style of programming was so poor, that it was practically unworkable.
He wasn't knocking Literate Programming; he was referring to the toolchains and debugging tools made it unbearable. That can be solved by better tools.
For me, good comments are useful, and are welcome. Bad comments are not useful, and I delete them.
A good comment explains WHY something is the way it is, HOW TO overview, or is a TODO.
A bad comment adds no value.
Because it is repeating what the code is doing,
x = x + 1; // Increment x by one..Or because the comment is incorrect,
document.save(); // Load the documentOr because it could be made unnecessary by writing better code.
int x = 0; // x is the person's age.-->int age = 0;Or because the comments are scaffolding for when creating the code. Including pseudo-code. Once the code is created, the pseudo-code and "mini TODO" comments become unnecessary. And over time, the code will evolve making those comments incorrect. (My C++ project is 32 years old. There are a lot of those kinds of misleading comments.)
I think those kind of bad comments we can all agree are not useful. And, unfortunately, these are not contrived strawman examples.
Now if I was programming in Glass, I'd probably have a different take on comments. But I'll wait for Microsoft IronGlass#.NET before worrying about it. ;-)
Thanks Eljay-Adobe. Excellent discussion. Another thing I came across recently is the use of TODO comments. Apparently it is somewhat of a software security risk. We got flagged for that at work, although just LOW priority. To resolve them, just make sure to implement the code and remove the comment.