Right, this is exactly the argument we are making. Given just the block of code above, we don't know enough to make the determination. Who is right? We can't possibly no without more. That's why commenting code is not enough, and that's why literate program is important.
Imagine if you came across this in actual code. You might first check if the code was changed recently and by whom, and whether the comment or the code came first. But that still wouldn't tell the whole story. To get it all, you would find out who checked in the code, and what their original intent was.
What we're advocating is to treat source code more like a design document. It's a collection of thousands of design decisions all informing the specification of the final product, the program.
> If the idea is simply that this is extra work for the programmer to do -- that they need to describe every implementation twice, once in code and once in English
Right, so the point is that prose is not redundant. As Knuth put it literate programming is "a mixture of formal and informal methods that reinforce each other." When we communicate to one another face-to-face, we use gestures, expressions, intonation, etc. to articulate an idea. On the internet, when we communicate with just text, much of my meaning is lost forever and never apparent to anyone who reads this.
Programming is much the same way. The code only tells you so much about the program. Without any context, readers are often disoriented and confused by new codebases. If no one is willing to read your code, no one will ever contribute to it. GitHub and SourceForge are veritable graveyards of amazing yet abandoned projects that will never see another contribution, because their codebases are so inscrutable. I know I'm guilty of this as well; when I revisit old codebases, I hardly know even what I was thinking.
Anyway, I think there's a lot to explore here. I think what you raise is an issue, and it will always be important to address, but I really believe that literate programming is important and can lead to better code. So we're going to see where we can take it with Eve, and I hope you'll give it a shot!
Well, I did skim a little bit through Eve's source code, specifically the files in https://github.com/witheve/Eve/tree/master/src and subs, and the first thing that stroke me was: it's not literate. As a matter of fact, it doesn't have more comments than an average code base, maybe even less.
Why? Where is the prose? What makes programs supposed to be written in Eve different from Eve itself?
Trying to do literate programming in traditional languages is pretty crappy [1]. Some heroic effort ended up having to go into this release as well so things aren't as commented as we wanted, but that will improve. There are a few files that are pretty good though [2].
Our Eve source on the other hand is wonderfully literate and it's been a really great experience. Here's the code that makes the inspector work [3].
I only looked at 2.. but honestly, that looked like the kind of code I got delivered from offshore teams. 3 lines of comments saying what a for loop will do, then 1 line to do the for loop. I would -1 most of that on a code review, and ask for comments that just describe what the code is doing to be removed.
Python is just "ugly" C underneath, containing for example a 1500 line switch statement, but this does not in any way change the fact that it's a great piece of software.
You didn't address at all what forces the programmer to keep the prose and code in sync. If you still have code that's read and translated by the compiler, and prose that's ignored by the compiler completely, how have you actually changed anything?
Well, I don't think anything can force the programmer to keep the prose and code in sync. The best we can do is give you an incentive to do so. The argument that was presented is that comments will get out of sync with code, but we're trying to provide tooling that will incentivize you to keep code and comments in sync.
I'd also like to say that if code is easier to read in the first place, there will be more eyes on it, and discrepancies will be resolved sooner. In most programming environments, a comment might describe a part of a much larger function. But the output of this code is far removed from the actual source. So discrepancies between comment and source are harder to spot.
It Eve, we intend these documents to be for more than just programmers. Who again, might not understand your code, but would understand the written prose and see the output /right there in the code/ that contradicts it. A bug like this would be brought to your attention much sooner than if your code was simply hosted as on GitHub.
Actual thing that will happen, if you're lucky: Dev changes the code to fix a bug, tests it, modifies it etc., finally gets it done. Deletes loving paragraphs of now obsolete text and writes in a one-liner description ("handle gravity effects")
Actual thing that will happen, if you're not lucky: Same as above, but they don't delete the obsolete paragraphs.
Every company needs a human-readable definition of what a product does. There is no way to eliminate the problem of keeping prose and code in sync. Traditionally, we just hide the problem by keeping the prose and code entirely separate. Keeping them together makes it harder for them to drift apart.
Your example doesn't make sense to me.
If I see a comment that says something different from what the code does I assume that the comment is wrong and I do a simple blame that will show me the jira that has been implemented in that code to double check.
For sure I don't need to read all that is specified in the Jiras whenever I look at any piece of code.
The code explains itself quite well.
If you write code that is not understandable then that is the problem, and adding thousands of comments in the form of documents will only make the things worse instead of solving your problem.
Imagine if you came across this in actual code. You might first check if the code was changed recently and by whom, and whether the comment or the code came first. But that still wouldn't tell the whole story. To get it all, you would find out who checked in the code, and what their original intent was.
What we're advocating is to treat source code more like a design document. It's a collection of thousands of design decisions all informing the specification of the final product, the program.
> If the idea is simply that this is extra work for the programmer to do -- that they need to describe every implementation twice, once in code and once in English
Right, so the point is that prose is not redundant. As Knuth put it literate programming is "a mixture of formal and informal methods that reinforce each other." When we communicate to one another face-to-face, we use gestures, expressions, intonation, etc. to articulate an idea. On the internet, when we communicate with just text, much of my meaning is lost forever and never apparent to anyone who reads this.
Programming is much the same way. The code only tells you so much about the program. Without any context, readers are often disoriented and confused by new codebases. If no one is willing to read your code, no one will ever contribute to it. GitHub and SourceForge are veritable graveyards of amazing yet abandoned projects that will never see another contribution, because their codebases are so inscrutable. I know I'm guilty of this as well; when I revisit old codebases, I hardly know even what I was thinking.
Anyway, I think there's a lot to explore here. I think what you raise is an issue, and it will always be important to address, but I really believe that literate programming is important and can lead to better code. So we're going to see where we can take it with Eve, and I hope you'll give it a shot!