|
in reply to Re^2: Programming *is* much more than "just writing code".
in thread Programming *is* much more than "just writing code".
I think you have some valid points, but there are some issues with having separate module documentation files. Apart from documentation not being directly under the maintainer's nose as I mentioned above, a lot of tools expect the docs to be in the same file as the code, so browsing it becomes an issue.
This could fairly easily be worked around, but on balance, I think it becomes a matter of personal choice, rather than one way being inherently superiour to the other. (There are ways to work around the problems of having it all in one file, such as having a good standard of what the format for each module should be, to keep out-of-place info creeping in).
But I think this is a separate discussion to your original point, which was on the merit of code annotations.
|
