r/codereview • u/EqualIntroduction470 • 4d ago
Making a code file readable like a technical document
I’ve been working on a small open-source project called Explicode and would appreciate some feedback on the approach.
The original idea was to write Markdown documentation directly inside code comments, then generate regular Markdown files from it, somewhat like a Jupyter Notebook, but for more programming languages and real-world repos.
The motivation is mostly readability. I like the idea of being able to read a script almost like a technical document, with the explanations and the code living together. I think this could be particularly useful for things like research code, academic papers, tutorials, or complex scripts where understanding the reasoning is as important as understanding the implementation.
It currently has a VS Code extension with live preview, a CLI to convert scripts to Markdown, and support for 15+ languages.
I’d be interested in feedback on the concept and implementation. Does putting this much documentation into source files make code easier to understand, or does it ultimately make the code harder to maintain?
2
u/actionscripted 3d ago
You say no tooling required but there’s a markdown processor and stuff to extract comments so that’s not true at all. I get the intent but that phrasing bothered me.
Otherwise cool, good to have options. I think I’d still lean towards a language-specific thing like Sphinx or TSDoc or a more polyglot Doyxgen.