Practice literate programming in Eve source code

[nmsmith]

Eve admirably advocates for literate programming by default. Taking an excerpt from the Eve developers' own exposition on literate programming:

While some held the view that programming languages are a way to communicate with a computer, Knuth argued the opposite: the purpose of writing a program is to communicate with another human being.

I think we can build a strong community to support and advance Eve and its ideals, but members of the community who wish to contribute will first need to develop a mental model of the current Eve implementation and understand all its intricacies. I'm sure we're all aware of how difficult it can be to reconstruct the mental model that a project's developers have in their heads by trawling through sparsely commented source code, so I propose that the core Eve team (and all future contributors) follow two development practices:

• For documentation at the code level, source code should follow the principles of literate programming as best as can be done under the constraints of traditional programming languages.
• For documentation at the project level, the architecture, design rationale, and near-term roadmap of Eve should be maintained in a shared wiki.

This is of course in addition to detailed documentation of all user-facing aspects of Eve.

I can appreciate the fact that Eve is highly experimental and rapidly iterating on the design is a good thing, so the level of documentation and the extent of the roadmap should be balanced accordingly, but we can do a lot better than the current state of things. I acknowledge that up until now Eve has almost exclusively been developed by Kodowa, but I think there's a lot to be gained from bringing more people into the fold to contribute to development and experimentation, and to offer new perspectives. I would love to be one of them. But a prerequisite for effective contribution is extensive source code (and project) documentation.

Of course, documentation doesn't only help new contributors. To quote from the developers once more:

When we're stuck or having trouble understanding something, one of the single most given pieces of advice is to attempt to explain it to someone else. This forces us to state our assumptions and fill in things we might have forgotten.

I'm looking forward to being part of this cultural shift towards more humane programming.

[ibdknox]

This is definitely something we're all for. For various reasons, we didn't have a chance to go back and clean things up, but we'll be taking the time to do so over the next few weeks.

[nmsmith]

That's great to hear. Looking forward to seeing the result :)

[piersmana]

@ibdknox Thoughts on an annotated replay mode down the line to help with constructing examples? Documentation is not the best way to pick up a new tool, and I think this has a lot of potential for technology education.

[ibdknox]

@atomic-swerve Yeah, we really wanted to do that before. I think that feature will largely fall out of our work on version control, but that's a ways off from now.

[nmsmith]

Still waiting for news on this front. Can we expect documentation/cleanup in the near future?

[cmontella]

The v0.3 release cleans up the directory structure, and the runtime is heavily commented: https://github.com/witheve/Eve/blob/master/src/runtime/runtime.ts

We'll have more updates on documentation when v0.3 is closer to release.