3 ms·
> I'm not sure I understand why someone in their IDE would be lost, you can't read README.md and see the file structure in your IDE? Of course one can see the
by jlg23 6y ago
> I'm not sure I understand why someone in their IDE would be lost, you can't read README.md and see the file structure in your IDE?
Of course one can see the files. But I rarely deal with "files" in my IDE, I deal with packages/namespaces/modules/functions/classes/methods. The natural place to put architecture documentation would therefore be the top-level code unit (e.g. package/module/namespace), to which one can easily navigate when viewing docs.
> Documentation in the source is different from a directory organization documentation.
Is it, given that directories tend to be organized around code units (again: packages/namespaces/modules/classes)? It is thinkable to store code in databases (see Dylan's IDE, either implemented or it was on the roadmap, I don't remember) and all the architecture documentation not directly attached to semantic units of your code would be lost.
- hashhar 6y ago100% agree. A very good implementation of your ideas can be found in the Redis codebase. Most important files have a long doc comment in the beginning. See https://github.com/redis/redis/blob/unstable/src/ziplist.c https://github.com/redis/redis/blob/unstable/src/ziplist.c for an example.
- baby 6y agoyour example is a comment of the code/implementation, related to the actual file, not to the architecture
- baby 6y agoI still don't think this is a good idea, after having worked a lot with Golang and Rust doc, the documentation generated from comments is targeted to users of the library, not contributors. (And Rust/Golang have the best documentation system out there of any language I have ever seen). For example, documentation in Golang does not follow your file structure, it just pulls up any public API comment and displays it. It makes sense, why would I care about how these functionalities are implemented and architected as a user? Second point: a system has different types of languages and ways to organize things, so it’s not always clear where to look for doc. Whereas a README is always obvious.