What are you all people coding that "comments are not necessary"?
Comments are absolutely mandatory, because code does not have any ways whatsoever of conveying all that essential information. Code tells you the "how" part of the story, and it's the most trivial part, derived nearly mechanically from the requirements. This coding part does not deserve even a tiniest fraction of attention it's getting from all those "clean code" practitioners.
The important part is the though process that lead to this particular wording of the requirements that was ultimately translated into the code. And if it's documented elsewhere, not along with the code itself, it'll get out of sync in no time.
Comments are absolutely mandatory, because code does not have any ways whatsoever of conveying all that essential information
I feel an example is required.
Here's my own personal project. Comment exist for documentation and in locations where my implementation has failed, I challenge you to suggest where comments are mandatory to increase uptake. Where unit tests and Javadoc fail to be more than enough.
Tell me where my code isn't "conveying all that essential information".
I challenge you to suggest where comments are mandatory to increase uptake
How can I do it? The information is already missing. It's not there. It cannot be deduced. You decided to withhold it, and since telepathy is not among my strong skills, I'm not in a position to suggest what exactly was on your mind when you wrote all of it. That's your job to explain all the background.
I don't know what were your performance considerations, why exactly did you choose this particular (and quite unusual) way of representing a CPU state, how do you mitigate the timing issues (as it's clearly not a cycle accurate emulator), and so on. It's all in your head, not written down anywhere in the code. Maybe you have some notes, maybe even a wiki, a pile of .doc files, etc., but it's all inaccessible from any of the relevant code. Finding it out requires effort at the very least, and asking you, the author, in the worst case scenario.
You need external sources in order to read your code, which is not a very good practice.
Well, 6502 won't ever change, it's solidified forever in the history, but think of a case where you're implementing some particular edition of an evolving standard - you'd have to put all the relevant standard paragraphs into your code in order to make it readable, along with documenting all your decisions on how to interpret undefined behaviour and implementation-specific cases.
Still, your code cannot be read properly without looking at a 6502 ISA spec on a side. And that's your conscious decision - you could have mixed it into your code to make it easier for anyone who'd read and maintain it.
20 years I've been a developer. I've never worked somewhere where 90% of the in code comments are found to be out of sync with the code they comment.
I simply don't believe it. I see stale Confluence pages pretty much on a daily basis. Not to mention that even if they're relevant, they're only relevant to the master and won't help at all if you're reading some older release branch. Confluence pages are not versioned under the same git repository as your code, and that's exactly what's wrong with them.
When code is only an illustration to a story, it reads much better than when the actual story is somewhere out there, requiring quite a bit of an effort to recover and put together. You see the big picture and all the details simultaneously, and you're naturally avoiding writing any excessive code.
Still, your code cannot be read properly without looking at a 6502 ISA spec
That is not the case at all. It seems you want every piece of information about the domain, about what the developer was thinking at the time, about every considerations has or ever will be. You want every choice to be documented even when they weren't a concern such as cycle accuracy and performance.
Firstly, that is not literate programming (it's a confused version of literate programming ad nauseam) and secondly good design in this case in Java is literate programming. Following the guidance of small methods, well designed class hierarchy and good Javadoc does in fact meet the standards of "code within comments" rather than your suggestion of "[excessive] comments within code".
It seems you want every piece of information about the domain, about what the developer was thinking at the time, about every considerations has or ever will be.
Yes. That's what I want to be assembled in one place. Because this is the important part. The code itself is only a derivative of all of these stuff.
You want every choice to be documented even when they weren't a concern such as cycle accuracy and performance.
The fact they're not a concern must be clearly documented, along with a reasoning.
Following the guidance of small methods,
That's my another pet peeve. I hate the very idea of radically small methods - it goes against the far more reasonable pattern-matching based approach to expressing things.
"code within comments" rather than your suggestion of "[excessive] comments within code"
Literate Programming is exactly code within comments, with more text than code. You can view it as code interleaved with tons of "excessive" comments if you wish, but in reality it's the code that's embedded in the story, not the other way around.
Then you are not here to protest the use of comments in how most of the world are programming, it's to suggested that most of the world are just programming completely wrongly. Despite most of the world abandoning your method as unmaintainable 30 years ago.
Literate programming was useful when domains and solutions became too much for weak languages. Maybe even still useful for horrible languages like Perl. Languages have evolved so towards writing expressive solutions in code which is runnable, testable and therefore verifiable.
Again, you're suggesting that the language can somehow express the "why" part. Sorry, but it cannot. No way. Even the most beautiful DSL would not ever be able to convey all that information.
And yes, most of the programmers are doing it wrong. Why would it even surprise you?
Just try to reflect on a fact that Literate Haskell exist and is quite popular. Or have a look at my example back in this thread - my language there is extremely high level, and yet it works much better when used in a literate code. Not to mention other literate systems that are very popular along with some very high level languages - Jupyter notebooks, for example, or Pweave.
No, I'm suggesting that the why part is irrelevant unless you have did something abnormally. If you drink tea, you don't need to explain why. If you drink horse piss, you can expect that people will want to know why.
Just try to reflect on a fact that Literate Haskell
Strange that you are strongly against small functions but use Haskell as an example in which small functions are a core part of the language.
systems that are very popular [...] Jupyter notebooks, for example, or Pweave
So popular in fact that in 20 years in the industry I've never met someone outside academia that use them.
If it takes few man-months and hundreds of thousands of $s to drink that tea, you'd better have a very good reason, very eloquently explained.
Writing code is a bad thing to do. You must always justify it.
as an example in which small functions are a core part of the language
Nope, there are very frequent cases where you'll have a large pattern matching, probably spanning across few screens.
So popular in fact that in 20 years in the industry I've never met someone outside academia that use them.
Please stop referring to your 20 years, or I'll start suspecting they're 1 year repeated 20 times.
I've been around for far longer, seen things. I perfectly understand what kind of industry you're talking about, and it's a very bad example. Nobody should ever try to reproduce methods common in such an industry. There are places in this industry where people do things in a much more organised way.
Please stop referring to your 20 years, or I'll start suspecting they're 1 year repeated 20 times.
Yet you can repeat your mantra 40 times. Everything is wrong except the way you do it, got it. You disagree with everything, nothing productive is being said and everything unproductive is being repeated.
It's not a "mantra", it's an objective observation. Your views of how this industry works are very evidently limited. You can get this kind of a tunnel vision only if you stick to something extremely repetitive and dull.
Again, how many Jupyter notebook users are out there? Your OOPish religion is a pile of crap, and you're way too deep in your zealotry to be able to admit it.
Once again, hundreds of thousands (at the very least) of the Jupyter users would laugh in your face.
Just have a courage to admit that you simply don't know enough to be able to reason about code quality and development practices. That'd be sufficient. And then start learning from scratch. And never again touch anything produced by this "uncle bob" unhinged preacher.
Also, please avoid having any strong opinions until you can reach the level of code quality of, say, TeX. As of Aug 2019, it have 8 bugs found and fixed. Good luck getting to this level of quality with this "clean code" religion of yours.
So you're admitting that you're deaf to all the rational arguments? That's exactly what zealotry is. That's exactly why the rest of the industry hates everyone who dares to even mention uncle bob.
zealotry: fanatical and uncompromising pursuit of religious, political, or other ideals; fanaticism.
Ideas such as literate programming.
Nobody is defending Uncle Bob. Asking you not to be insulting to and about everyone and anyone who doesn't share your idea that the solution to all programming problems is a paradigm rejected by the industry 30 years ago is NOT defending a single person. Nobody is being "fanatical" or "uncompromising" about the subject at hand, which is the value of comments in modern code. We (that is, everyone but you) are in fact having a polite discussion where I -as the proposer of said topic- am playing devils advocate to suggestions to the contrary. The only fanaticism I see and the only one being uncompromising is the one calling people names and strongly insinuating everyone but themselves is stupid, uneducated and/or backwards. The one who is quite clearly "fanatic" and "uncompromising" about a hatred of any and all Uncle Bobs ideas and of LP.
Jupyter users would laugh in your face.
So you're admitting that you're deaf to all the rational arguments?
you simply don't know enough to be able to reason about code quality and development practices
this "uncle bob" unhinged preacher.
please avoid having any strong opinions until you can reach the level of code quality of
you're all beyond any redemption
Looks like you always worked with some truly awful programmers.
This coding part does not deserve even a tiniest fraction of attention it's getting
So if you could stop acting like a petulant child, we've heard your arguments. They are off topic, uninterested and the approach you are selling is dead! Feel free to consider us scolded and give up.
I mean, you've clearly been having this argument for years with zero success, give it up.
is a paradigm rejected by the industry 30 years ago
Ok, I got it, you enjoy being an obnoxious liar. It suits you, actually.
and the approach you are selling is dead
Do you really think that your incompetent opinion on this topic matters? Really? You're ignorant, and it's your choice. You can either try to learn, or stay ignorant.
And yes, you're exactly a very convincing example of why people hate uncle bob zealots.
Matters enough for you to spend three days arguing with me about it.
You're a lost cause, as I stated pretty much straight away that uncle bob fans are beyond any hope. I'm providing arguments for passers by who might otherwise get swayed by your destructive preaching.
Never once defended Bob in any way and that makes me a zealot.
You're defending his position on in-line comments - that's sufficient, given that it's pretty much a core tenet of his religion. If you walk like a clean code zealot and quack like a clean code zealot, you're a clean code zealot by all practical means.
Third time: I'm not an uncle bob fanatic or even a fan. Never once even slightly indicated that might be the case. I proposed one of his assertions as a discussion to which you have thrown yourself at.
your destructive preaching.
Haven't preached once. You however...
You're defending his position on in-line comments
I'm playing devils advocate with a single assertion to promote healthy, polite discussion.
If you walk like a clean code zealot and quack like a clean code zealot, you're a clean code zealot by all practical means.
Appear to lightly agree with something == zealot. Yes, exactly the same thing. For a mathematician your logic is shocking. I can see why you need so many comments in your code, because you're clearly incapable of anything but typing and endless stream of completely illogical tripe.
I wont be responding to anymore of your nonsensical rubbish.
I proposed one of his assertions as a discussion to which you have thrown yourself at.
Not just one, but the most controversial one, which also happens to be the core belief of his entire "clean code" system. Everything else is immaterial in comparison.
Haven't preached once.
You keep insisting on a lie that in-line comments get stale in no time, because developers are lazy. And you propose a solution of having all that documentation elsewhere, because somehow magically it won't get stale this way. Which is 100% identical to all the arguments of uncle bob and his unhinged followers. You walk like them, you quack like them, you're one of them. By definition. No matter what your motivation for taking this position is.
I'm playing devils advocate with a single assertion to promote healthy, polite discussion.
And you just demonstrated your own project that practices exactly what you preach here. So much for a devils advocate.
Also, what "healthy discussion" you're talking about, if you dismiss all the arguments of why the opposite approach works better as "trust me, I have 20 years of experience, so take my word that it's not how the industry works, it was abandoned 30 years ago, and don't you even dare to argue, because I have 20 years of experience" (and then repeat it a dozen of times more, in case if someone missed the super important fact that you have 20 years of experience). The funny thing here is that you honestly believe that you even have sufficient credibility to speak for the entire industry. Your attitude to arguments is as far from anything "healthy" as possible, so don't be surprised when people treat you like a troll.
Appear to lightly agree with something == zealot. Yes, exactly the same thing.
Not just "something", but the defining tenet of the religious system. Believing in the core beliefs of a religion makes you a follower. And the fact that you find this solid logic "shocking" is pretty much consistent with everything else - your OOP zealotry, your lack of experience, your misguided manners.
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.
What are you all people coding that "comments are not necessary"?
Comments are absolutely mandatory, because code does not have any ways whatsoever of conveying all that essential information. Code tells you the "how" part of the story, and it's the most trivial part, derived nearly mechanically from the requirements. This coding part does not deserve even a tiniest fraction of attention it's getting from all those "clean code" practitioners.
The important part is the though process that lead to this particular wording of the requirements that was ultimately translated into the code. And if it's documented elsewhere, not along with the code itself, it'll get out of sync in no time.
I feel an example is required.
Here's my own personal project. Comment exist for documentation and in locations where my implementation has failed, I challenge you to suggest where comments are mandatory to increase uptake. Where unit tests and Javadoc fail to be more than enough.
Tell me where my code isn't "conveying all that essential information".
github.com/rossdrew/emuRox
20 years I've been a developer. I've never worked somewhere where 90% of the in code comments are found to be out of sync with the code they comment.
How can I do it? The information is already missing. It's not there. It cannot be deduced. You decided to withhold it, and since telepathy is not among my strong skills, I'm not in a position to suggest what exactly was on your mind when you wrote all of it. That's your job to explain all the background.
I don't know what were your performance considerations, why exactly did you choose this particular (and quite unusual) way of representing a CPU state, how do you mitigate the timing issues (as it's clearly not a cycle accurate emulator), and so on. It's all in your head, not written down anywhere in the code. Maybe you have some notes, maybe even a wiki, a pile of .doc files, etc., but it's all inaccessible from any of the relevant code. Finding it out requires effort at the very least, and asking you, the author, in the worst case scenario.
You need external sources in order to read your code, which is not a very good practice.
Well, 6502 won't ever change, it's solidified forever in the history, but think of a case where you're implementing some particular edition of an evolving standard - you'd have to put all the relevant standard paragraphs into your code in order to make it readable, along with documenting all your decisions on how to interpret undefined behaviour and implementation-specific cases.
Still, your code cannot be read properly without looking at a 6502 ISA spec on a side. And that's your conscious decision - you could have mixed it into your code to make it easier for anyone who'd read and maintain it.
I simply don't believe it. I see stale Confluence pages pretty much on a daily basis. Not to mention that even if they're relevant, they're only relevant to the master and won't help at all if you're reading some older release branch. Confluence pages are not versioned under the same git repository as your code, and that's exactly what's wrong with them.
Have a look at some proper Literate Programming examples - TeX The Book, or some lighter read like, say, this one: wyag.thb.lt/ - or this one combinatorylogic.github.io/mbase-d...
When code is only an illustration to a story, it reads much better than when the actual story is somewhere out there, requiring quite a bit of an effort to recover and put together. You see the big picture and all the details simultaneously, and you're naturally avoiding writing any excessive code.
That is not the case at all. It seems you want every piece of information about the domain, about what the developer was thinking at the time, about every considerations has or ever will be. You want every choice to be documented even when they weren't a concern such as cycle accuracy and performance.
Firstly, that is not literate programming (it's a confused version of literate programming ad nauseam) and secondly good design in this case in Java is literate programming. Following the guidance of small methods, well designed class hierarchy and good Javadoc does in fact meet the standards of "code within comments" rather than your suggestion of "[excessive] comments within code".
Yes. That's what I want to be assembled in one place. Because this is the important part. The code itself is only a derivative of all of these stuff.
The fact they're not a concern must be clearly documented, along with a reasoning.
That's my another pet peeve. I hate the very idea of radically small methods - it goes against the far more reasonable pattern-matching based approach to expressing things.
Literate Programming is exactly code within comments, with more text than code. You can view it as code interleaved with tons of "excessive" comments if you wish, but in reality it's the code that's embedded in the story, not the other way around.
Then you are not here to protest the use of comments in how most of the world are programming, it's to suggested that most of the world are just programming completely wrongly. Despite most of the world abandoning your method as unmaintainable 30 years ago.
Literate programming was useful when domains and solutions became too much for weak languages. Maybe even still useful for horrible languages like Perl. Languages have evolved so towards writing expressive solutions in code which is runnable, testable and therefore verifiable.
Again, you're suggesting that the language can somehow express the "why" part. Sorry, but it cannot. No way. Even the most beautiful DSL would not ever be able to convey all that information.
And yes, most of the programmers are doing it wrong. Why would it even surprise you?
Just try to reflect on a fact that Literate Haskell exist and is quite popular. Or have a look at my example back in this thread - my language there is extremely high level, and yet it works much better when used in a literate code. Not to mention other literate systems that are very popular along with some very high level languages - Jupyter notebooks, for example, or Pweave.
No, I'm suggesting that the why part is irrelevant unless you have did something abnormally. If you drink tea, you don't need to explain why. If you drink horse piss, you can expect that people will want to know why.
Strange that you are strongly against small functions but use Haskell as an example in which small functions are a core part of the language.
So popular in fact that in 20 years in the industry I've never met someone outside academia that use them.
If it takes few man-months and hundreds of thousands of $s to drink that tea, you'd better have a very good reason, very eloquently explained.
Writing code is a bad thing to do. You must always justify it.
Nope, there are very frequent cases where you'll have a large pattern matching, probably spanning across few screens.
Please stop referring to your 20 years, or I'll start suspecting they're 1 year repeated 20 times.
I've been around for far longer, seen things. I perfectly understand what kind of industry you're talking about, and it's a very bad example. Nobody should ever try to reproduce methods common in such an industry. There are places in this industry where people do things in a much more organised way.
Yet you can repeat your mantra 40 times. Everything is wrong except the way you do it, got it. You disagree with everything, nothing productive is being said and everything unproductive is being repeated.
It's not a "mantra", it's an objective observation. Your views of how this industry works are very evidently limited. You can get this kind of a tunnel vision only if you stick to something extremely repetitive and dull.
from the guy selling a paradigm invented in 1983 and largely abandoned in 1984.
Again, how many Jupyter notebook users are out there? Your OOPish religion is a pile of crap, and you're way too deep in your zealotry to be able to admit it.
Go sell literate programming somewhere else. Nobody cares about your insulting, arrogant, ancient views.
Once again, hundreds of thousands (at the very least) of the Jupyter users would laugh in your face.
Just have a courage to admit that you simply don't know enough to be able to reason about code quality and development practices. That'd be sufficient. And then start learning from scratch. And never again touch anything produced by this "uncle bob" unhinged preacher.
Also, please avoid having any strong opinions until you can reach the level of code quality of, say, TeX. As of Aug 2019, it have 8 bugs found and fixed. Good luck getting to this level of quality with this "clean code" religion of yours.
Whenever you are finished repeating yourself, feel free to go find a discussion relevant to your dead paradigm.
So you're admitting that you're deaf to all the rational arguments? That's exactly what zealotry is. That's exactly why the rest of the industry hates everyone who dares to even mention uncle bob.
Ideas such as literate programming.
Nobody is defending Uncle Bob. Asking you not to be insulting to and about everyone and anyone who doesn't share your idea that the solution to all programming problems is a paradigm rejected by the industry 30 years ago is NOT defending a single person.
Nobody is being "fanatical" or "uncompromising" about the subject at hand, which is the value of comments in modern code. We (that is, everyone but you) are in fact having a polite discussion where I -as the proposer of said topic- am playing devils advocate to suggestions to the contrary. The only fanaticism I see and the only one being uncompromising is the one calling people names and strongly insinuating everyone but themselves is stupid, uneducated and/or backwards. The one who is quite clearly "fanatic" and "uncompromising" about a hatred of any and all Uncle Bobs ideas and of LP.
So if you could stop acting like a petulant child, we've heard your arguments. They are off topic, uninterested and the approach you are selling is dead! Feel free to consider us scolded and give up.
I mean, you've clearly been having this argument for years with zero success, give it up.
Ok, I got it, you enjoy being an obnoxious liar. It suits you, actually.
Do you really think that your incompetent opinion on this topic matters? Really? You're ignorant, and it's your choice. You can either try to learn, or stay ignorant.
And yes, you're exactly a very convincing example of why people hate uncle bob zealots.
Matters enough for you to spend three days arguing with me about it.
Once again. Never once defended Bob in any way and that makes me a zealot.
Give. Up. Griffiths.
You're a lost cause, as I stated pretty much straight away that uncle bob fans are beyond any hope. I'm providing arguments for passers by who might otherwise get swayed by your destructive preaching.
You're defending his position on in-line comments - that's sufficient, given that it's pretty much a core tenet of his religion. If you walk like a clean code zealot and quack like a clean code zealot, you're a clean code zealot by all practical means.
Third time: I'm not an uncle bob fanatic or even a fan. Never once even slightly indicated that might be the case. I proposed one of his assertions as a discussion to which you have thrown yourself at.
Haven't preached once. You however...
I'm playing devils advocate with a single assertion to promote healthy, polite discussion.
Appear to lightly agree with something == zealot. Yes, exactly the same thing. For a mathematician your logic is shocking. I can see why you need so many comments in your code, because you're clearly incapable of anything but typing and endless stream of completely illogical tripe.
I wont be responding to anymore of your nonsensical rubbish.
Not just one, but the most controversial one, which also happens to be the core belief of his entire "clean code" system. Everything else is immaterial in comparison.
You keep insisting on a lie that in-line comments get stale in no time, because developers are lazy. And you propose a solution of having all that documentation elsewhere, because somehow magically it won't get stale this way. Which is 100% identical to all the arguments of uncle bob and his unhinged followers. You walk like them, you quack like them, you're one of them. By definition. No matter what your motivation for taking this position is.
And you just demonstrated your own project that practices exactly what you preach here. So much for a devils advocate.
Also, what "healthy discussion" you're talking about, if you dismiss all the arguments of why the opposite approach works better as "trust me, I have 20 years of experience, so take my word that it's not how the industry works, it was abandoned 30 years ago, and don't you even dare to argue, because I have 20 years of experience" (and then repeat it a dozen of times more, in case if someone missed the super important fact that you have 20 years of experience). The funny thing here is that you honestly believe that you even have sufficient credibility to speak for the entire industry. Your attitude to arguments is as far from anything "healthy" as possible, so don't be surprised when people treat you like a troll.
Not just "something", but the defining tenet of the religious system. Believing in the core beliefs of a religion makes you a follower. And the fact that you find this solid logic "shocking" is pretty much consistent with everything else - your OOP zealotry, your lack of experience, your misguided manners.