I was thinking about your layers after looking at mu and subx, and also the way RFCs are sort of like layers <write.as/365-rfcs/table-of-con>. I don't know for sure about code itself being divided down in this way but documentation done this way is very approachable. and maybe literate programs as a merge.

@rain Awesome! By "merge", did you mean using the same layers for docs as well as code?

Yeah, I think layers are awesome for code :) I'd love to hear more about your reservations.

One thing that is maybe not obvious is that my layers are really designed to live in your text editor as you build the system, run subsets of layers, run a single test, inspect the log, and so on. Connecting with Literate Programming is perhaps a liability; my layers are definitely not designed to just be read.

@akkartik @rain To be fair, neither is Knuth's LP approach either. :)

Regarding using the same layer for both docs and code, you may recall that the only thing I didn't find in your system was a mechanism by which you could update multiple files in the project for a given layer. Given that feature, you should be able to do not just cross-module updates, but also documentation updates as well.

@vertigo Yeah, that's fair. As they stand now, layers are a "take over the world" idea. I think it gets too confusing to have modules and layers at the same time. So I use layers for managing complexity, and the modules the compiler sees are a low-level detail just to improve build time. My tangler automatically 'cleaves' the results into modules.

I'm not sure how you conclude LP is for more than reading. The whole emphasis on typography and rendering to xvi/pdf seems about printouts.


@akkartik @rain Implementation detail.

Nothing in LP says you must emit TeX sources for documents. Markdown or even plain text is doable.

But, LP has always been about writing correct software. The reason Knuth invented the idea in the first place was to control complexity in writing large-scale Pascal programs.

@akkartik @rain Yes, the intended result *is* for reading -- obviously, since human code review is a fantastic asset to have. But it is *also* for writing software. TeX and LCC are themselves examples. See en.wikipedia.org/wiki/LCC_(com

@akkartik @rain Though not explained how it works, my hypothesis is that it relies on the same neuro-chemical processes as "rubber duck debugging" (en.wikipedia.org/wiki/Rubber_d). Writing clear explanations for your code suitable for print and intended for a wide audience helps you clarify your requirements and implementation details so that they have a greater probability of agreement.

Just as explaining your code to a rubber duck helps you work through problems, so too does describing it in prose.

@akkartik @vertigo

it's kind of interesting how the layers approach means you have N valid programs, nested. This isn't really a difficult constraint because this is the way we develop software anyway.

@akkartik @vertigo

the other approach to this is git history. Maybe it's because my text editor doesn't have integration but I've basically never went back and forth through git commits to get used to a codebase.

Part of the git history holds mistakes and minor fixes. Each layer is - up to current knowledge - correct.

@rain @akkartik Git would work well if you could colocate relevant code with relevant description. Unfortunately, you cannot: the git commit log is a logically separate structure from the code.

The other advantage that the explicit layering approach has over using git is that mistakes can be corrected in the base layers of a program and can be tracked in git without cluttering the prose that the code reader would normally read. If just using git, you'd need to be perfect at all times.


@vertigo @akkartik I realized earlier you could automatically convert layers to a git repo. 1 commit per layer. Viewing the file with changes in green could be very useful. It's interesting to think about the rough equvialence between layers and a git commit history. The git history is a bit more messy whereas the layers are kind of a updated perfect version of the git history.

Sign in to participate in the conversation

Welcome to your niu world ! We are a cute and loving international community O(≧▽≦)O !