Eve: Programming designed for humans

In his case, his algo said X, and his code did Y.. very easy to see the mistake.

In your case, lets add a comment

// Note: PCI-DSS requirements apply below

Now 3 years later, the law changes and the requirements do not apply. So you are at the same situation. Code does X, comments say Y. Which is right?

Not a very easy to keep comments and code in sync

Actual thing that will happen, if you're not lucky: Same as above, but they don't delete the obsolete paragraphs.

> An IDE like Medium, not Vim

Thing is, vim is not complicated because of some misplaced elitism, vim is complicated because it helps with complicated problems. (I am a zealot for the church of Emacs, when I say something "nice" about vim, it is because honesty or pointy objects force me.)

Unfortunately it goes downhill from there, it is nice that there is a way to visualize memory in five lines of code, but what about the memory of the following three processes (and the one thread in red and the others in some other color?) In my experience, there is a trade off between the power of a language and the impressiveness of the examples. (A better example would probably be the twitter api, does that mean I need to beg the core developers to talk to the next "slack for dogs" api?)

Then there is the "zoom" feature, I have not the slightest idea what that is supposed to mean. (Actually I have, I just don't think that this side of a strong AI coworker it is possible to hide information in any useful way. (Hiding information is just the inverse of zoom.)

And to top it of, there is a link to the demo and the first thing I notice is, scrolling is broken. (Arch, Firefox, NoScript with in this case all JS sources allowed) Well, the first thing a IDE should allow me to do is to display text in the most reliable way possible, even if that means more than one page. (Plus it is in a browser, which may or may not be only for demonstration purposes, but at the very least the browser uses the right mouse button to display browsery options not IDE options.)

After having fired up chromium, there the IDE works and it actually works kind of well. To keep with the overall negative tone of the comment, almost as good as Jupyter. The first thing I notice, is that one can switch code blocks on and off, but the output depends non linearly on the set of switched on code blocks. For this one would likely need some kind of toggles for sets of code blocks if it should be usable at all. (So to switch on extra test cases, or to test only one part of the program, etc.)

In conclusion, it is a nice project and I wish the devs all the best. Hopefully one of these days someone manages to get literate programming to work. But I think that there are quite a few things which make me doupt that this is, what makes literate programming work in the end.

Because in large, logically complex systems, especially large complex systems that are sold to many customers like my area of expertise, ERP systems implementation & development, there are many, many right answers (there are many wrong answers, too). Take inventory costing; my current project is adding an industry specific inventory handling methodology to an existing ERP system. Consider the inventory unit costing: there are multiple methods (standard, weighted average, FIFO, retail method, etc.), there can be different derivations and components (purchase cost, landed costs, material costs, direct overhead cost, indirect overhead costs) and to top things off, not only do systems implement more than one of these at a time, sometimes different of these can be useful concurrently depending on context: if I'm analyzing my vendor costs per item, I might not want my overhead costs in the picture, but I still need overheads in the capitalized cost of the item when determining Cost of Goods Sold when I ship product out, for example. In software, if I see a function like (not real, way oversimplified pseudo-code):

function calc_item_trans_cost() { total_item_trans_cost = item_cost + item_freight_cost return total_item_trans_cost }

I might not know exactly where or how to use this properly, even having some expertise. Was the developer trying to get at a landed cost? Are they expecting that this would only be used in the invoice matching process and shouldn't really be used outside of that? I might get that contextually from surrounding code or from the (various) contexts that the function is called in, but now I have a research project trying to figure out why they created this so that I don't use it in inappropriate contexts... or I can re-invent the wheel (not a good strategy). My professional knowledge will tell me where to look for other telltale signs to figure out the answer, but not immediately just from looking at the code since there are multiple valid answers. If I had:

// Function for determining item costs for three way matching. // We record freight costs separately from item material costs, // but invoices have no such breakout, so we do the math here // to facilitate the matching process.

function calc_item_purch_cost() { total_item_purch_cost = item_cost + item_freight_cost return total_item_purch_cost }

now I get it. It's not that the system has a simplified view of landed costing, but there is a specific purpose that was trying to be accomplished by this function.

> You already know what the code is supposed to do anyway, why introduce a comment that you might later forget to update, leaving less knowledgeable colleagues confused?

Most of the time the comments in the code I work with really don't change much in regard to intent. If the comments get too close to describing the logic, then yes, the comments don't age well as the logic that achieves that intent is improved, but those are the comments that are probably not needed. The contextual comments, however, are important (even for me to understand what I wrote after some time has passed).

Even so, I was speculating/rationalizing on why people might hold that somehow "ignorance is bliss" when I spoke of junior staff. I don't hold that belief myself. I haven't found that withholding information even from junior/support staff is better than giving more complete pictures. I find the informed person much more useful that the person guessing at what it could all possibly mean and fit together.