Hacker News Reader

Comment by qbasic_forever | Hacker News Reader

Or IMHO this is much better solved with a literate programming approach where the tour content lives inside the code as comments. Then as code is refactored and changed it's very obvious that the related docs and tour data has to change too.

View on HN

With CodeTour, you can have "content only steps" (introductories, interstitials), steps that speak to directories, and also, add steps to files that don't necessarily support comments (e.g. JSON). So there seemed to be some value in having the tour be more flexible, than what what might be achievable code comments alone.

Additionally, after speaking with a bunch of folks, there are definitely teams that weren't interested in "polutting" their code with comments that might be tailored to onboarding new team members, and therefore, didn't need to be always visible.

That said, I totally agree with the value of a literate programming-based solution. But there may also be some nice properties to a "side car" file as well, and so I'm primarily trying to explore how well we could make that work, in a resilient and easy-to-maintain way. We'll see how it goes!

> there are definitely teams that weren't interested in "polutting" their code with comments

Add an extension feature that toggles (hides/shows) those comments maybe?

Not an equivalent of literate programming. Here you can jump to arbitrary files at arbitrary points, in literate programming your code must flow from top to bottom linearly, which is most of the times impossible to achieve.

No not with Knuth's original ideas for literate programming and cweb. There's an explicit abstraction between the location of prose and the final source code output and they can be woven in any way the author desires. You can even insert intermediate steps, like pseudocode that show building up the architecture in small incomplete steps, and all of that is removed entirely from the final source code result. It is actually quite complex and why more modern literate programming systems ditch it and basically turn into fancier comments.

Sure, I get your point, but this description stands in opposite to previous statement that “tour content lives inside the code as comments”.

It seems to me that CodeTour is very close to Knuth’s idea.

I recommend reading up on cweb and its history. The tangling and weaving metadata and prose lives in the code with special fenced blocks. Noweb is a modern version of it: https://github.com/nrnrnr/noweb (but it's not really used or maintained much anymore)

Agreed.

But many developers might be very much against littering code with such tour comments, and be very much opposed to any kind of responsibility of updating tours during refactoring.

Me included.

Reply on news.ycombinator.com