How about Knuth’s concept of Literate Programming? Beyond merely interspersing comments, a literate programme freely mixes computer language with documentation.
How popular is this paradigm? Knuth is a famous computer scientist, but he does not need to worry about things like large enterprise systems.
As for pure mathematics or applied mathematics, mathematics papers are closer to literate programming in the sense that mathematical writing relies on natural language as much as it uses (hopefully well-chosen) notation and jargon. But they are not computer programs, and there is a huge gap between the limited set of mathematical proofs that can be read and checked by a computer and what people typically write. A well-written mathematical article seems to rely on the creativity and style of the author beyond merely choosing apt names for the variables. Also note that many of them, though there are exceptions, are of moderate length [checking the daily “new submissions”: 18 pages, 14 pages, 31, 15, 14, 26, 28, 29, 7, …] compared to an enterprise computer program.
I will say that we are in the dark ages when it comes to solving the problem of modeling systems in a way that can be used to both communicate to users and maintainers about it’s function, and that those same specs (or something derived from them) drive the execution. I think what could work is some sort of 3D model (abstract, hiding details unless drill in) that evolves over time according to input and that allows us to single out specific features and functions to see impact across a large system.
I don’t see where you said anything positive about comments. Comments in functions, except very simple ones, have the same benefit as comments anywhere else.
If you are explaining why you are doing something, the choices are inside the code or in an external document. Or both, which is best.
Do you agree that compilers can’t catch “lies” about functions? Testing might if they cause a logic error, but I’m not even sure what you mean by them.
I’m confused. It’s my normal state, but bear with me. If you are hit by object X moving at v, won’t it hurt the same if a=0 or if it’s accelerated to v when it hits? And I’m not sure what d is because you didn’t define your terms.
If you’re working in a language with global variables, yes, they need to be named descriptively. Especially if it lacks namespaces to store them in. Or if you’ve inherited legacy code where the scope is pages and pages long, then yes, it’s a necessary survival skill to to have self-describing variable names.
But if your program is broken down into lexically scoped functions no more than a half page long, then verbose naming of local intermediate products is just distracting. It also attracts “readability tweaks” (maybe I think I have a better name than yours). Better to make the point "this is X, it isn’t important, it will only be in scope for a couple more lines anyway).
I take pains to explain my reasoning because we should be talking about general principles rather than universal practices. Again, much depends on your context and tooling.
You’re hurt by the acceleration you cause in object X - a ball that hits you in the stomach hurts more if it decelerates quickly (by hitting unprotected flesh) than it does if it decelerates slowly (by (say) hitting a pillow strapped to your stomach).
Again, researchers study this stuff. The results are unambiguous. for example, I saw a study where a “reverse text” function (about 10 lines) was studied by experienced programmers, one group had meaningful variable names and one group did not (e.g. a,b,c,etc.).
The group with meaningful names understood the code 2 to 3 times faster than the other group.
Good variable naming is even more important than comments.
I figured it was something like that because “d” meaning a change in something made somewhat more sense than it meaning distance, but the only calculus I know is what I made up, like dividing the area under a curve into a bunch of skinny trapezoids and throwing in a miniscule fudge factor. Easier done on a CAD system than a drawing board.
In general, I believe that self-documenting code was a move forward. Comments are better, but people never write them; they do better with function and variable names.
But I have also seen it move things back towards spaghetti code, because you’re solutions logic across a random assortment of mini functions scattered in no particular order all over the place (and, in one instance I’ve seen, creating extra layers of objects and factories) and encouraged people to not comment. I received one review asking me to remove a comment in favor of a long function name, for a single line in a short function.
At any rate, whatever the best setup is for code, it’s certainly better than what math is doing even if we’re still narrowing in on the right answer.
I said that those technologies encouraged brevity (because it’s a PITA to write on them). My comments about scratching things out was in the discussion of paper and only paper.
Given that we’re discussing the language of math, I would presume it to include at least a proof.
Since that language seems to also require the ability to formally state and describe propositions, theories, etc. Some of that might also be in there, depending on how industrious the library writer was feeling.
I might also expect some calculus imports and the ability to click into the proofs of differentiation and such.
Hm. Bizarre. The amount of force I get hit with is independent of the current velocity, just how quickly it’s changing? Whether a bullet is traveling at 1 m/h or 1000 m/s, it will have the same force so long as it was traveling at an equivalent difference of speed in the previous measurement period?
If it’s not a thing that needs proving, it’s more just a “useful macro” for various purposes, then probably I would expect to see proofs of its ability to fulfill those purposes, similar to unit tests in code.
Other way around (as I explained a few posts ago). The force you get hit with depends on how quickly your body changes the velocity from the current velocity to zero. Drop a glass onto a concrete floor from a distance of 4 feet - the velocity changes from about 16 feet per second to zero very quickly, and the glass breaks. Drop it from four feet above a cushion and the velocity changes from 16 feet per second to 0 over a significantly longer time - and the class doesn’t break. The acceleration before the collision doesn’t matter - it’s the acceleration (deceleration) during the collision that matters.
It is my no means consistent or universal, but I see that some authors do make at least a token effort to prepare a PDF file with hyperlinks, so that clicking on a mention of “Definition 1.2.3” or “Theorem 4.5.6” takes you to that part of the paper, and clicking on an external reference takes you to the bibliography and/or brings up the actual article in question.
As for basic properties of the gamma function, there may be no references in the paper you read because the author assumes you already know what he or she is talking about, or at any rate can easily look it up. It’s not some esoteric function nobody has heard of, in which case one would expect at least a definition and further references.
You’ve stated this twice as fact, and this is GD, so I’ve gotta call “cite” on this.
10 lines for reverse text? The variable names aren’t the real problem in this example. You could do this in a single line of Ruby code (two lines if you’re reading from a file).
This is just to call out (again) that best practices are very much context-dependent. It’s not an admonition to switch to Ruby, but… if you find yourself spending a lot of time scrupulously naming and commenting functions that could be trivial, maybe you need to be looking at a different toolset.
http://www.cs.loyola.edu/~lawrie/papers/lawrieICPC06a.pdf
“6 Summary and Future Challenges
The study described in this paper shows that better comprehension is achieved when full word identifiers are used
rather than single letter identifiers as measured by description rating and confidence in understanding.”
“The conclusion of this report is that the readability and interpretation of code
was improved by the introduction of certain code styling features. As for code
indentation and syntax highlighting, no visible improvement was observed.
Code commenting, however, caused the subjects to examine the method signatures in a code more thoroughly and thus detecting return-type-related
errors hidden within; a visible improvement. Furthermore, logical variable
naming rids the programmer of the trouble of having to read entire pieces
of code that could otherwise, when used cleverly, be explained by a method
or variable name itself, and thus improved readability and interpretation as
well.”
“In all three methods the time
it took participants to reach comprehension under the
8
control treatment was shorter than the time needed with
the experimental treatment, where variable names were
replaced by a, b, c, and so on.”
You think it’s a problem that in some languages, it takes about 10 lines to write a reverse function?
Please help the rest of us understand, why is that the “real” problem? And what exactly about it is the “real” problem?
Do you think a language exists in which every single computable function is smaller in that language than all others? If you don’t think that then why did you focus on this combination of one function and the comparison of two specific languages?
Should we switch our 20 million lines of code every time a new language introduces a built in function that saves a few lines? “Hey guys, start the rewrite, there’s a new language that does the reverse function in just 3 letters, you don’t have to spell out the entire word, you just type in REV”
I was going to ask you how much experience you have, but no need, the question has been answered.
