Hacker News Reader

Comment by noir_lord | Hacker News Reader

Something I've considered on and off is that our current way of writing code is insufficient, I'd really like to have an editor/IDE that had "layers" so that I could attach code related comments in one layer and intent/documentation in another layer - throw in the ability to hide/show layers at will and you'd have a much more flexible way of documenting code than we currently have.

View on HN

You could probably hack this into an editor with folding support, such as Vim. Just tag each layer with a different folding marker, and bind a hotkey to open/close all folds for that layer.

http://vim.wikia.com/wiki/Folding

I do worry about programmers forgetting to check hidden layers even more than we may currently tend to ignore comments, so I worry about this adding parallel maintenance burdens even worse than the common problem of comments getting out of date with the code. Maybe there could be some way to have compile-time diagnostics or static tools to enforce updating of the documentation layers with the code. Though that could add obstacles to adoption, as the tools and meta-concepts would have to evolve along with the layering concept itself.

It was possible do it with literate programming for ages. Combine it with emacs, mmm-mode and, say, auctex - and you'll get your IDE.

I used litcoffee* for a while, and it really makes you think about and code for a future reader / maintainer, which is pretty great.

It really slows you down though (good thing?) when trying to dump your ideas into code, especially if you end up writing exploratory code that you later delete (I do this a lot).

I think literate code could be really great however for refactors. Once you've figured out the correct implementation and have the time & hopefully budget to revisit your fast code. Maybe it won't feel like the chore of straight up documentation, and more like the enjoyment of polishing your art.

* http://coffeescript.org/#literate

Interesting. My experience is different - I write my throwaway code starting with a free form prose, dumping all my vague ideas into a text, which is then filled with a very volatile code to explore the listed ideas. It results in a mess, of course, but a mess with a track of what I tried to achieve.

I'd always rewrite what is left of such an effort from scratch, but it is easy to do so with all the literate brain-dump surrounding my code.

Definitely a different approach. I think I will try that. I would imagine you end up refactoring the documentation as much as the code.

I pair quite a bit these days, and this may compliment our process nicely.

IMO that's sort of what some forms of testing are designed to accomplish, in a way which is a little less-prone to unattended divergence or rot.

Reply on news.ycombinator.com