Paste: rationale for directory-per-module
Plain Text |
|Date: ||Sun, 29 Aug 2010 17:25:55|
In most programming languages the API documentation for a module is
inlined within the source code. I find that unsatisfactory for two reasons:
1) The documentation is itself difficult to read because it contains
markup meant to make it look good when viewed in a browser.
2) In many cases the documentation is soo large that it interferes
when trying to read the code.
So it's a good idea to keep the source code and the api documentation
in two separate files. This was the motivating reason for requiring a
separate directory for every module. The plan is to use the module's
directory for storing multiple different files related to the module
e.g: source code file + docs file + unit tests file
I borrowed this design from Factor.