4 ms·
> the directions said to code as you would professionally, and that means I should comment my work. Were this a "professional" component/service, in perhaps th
by neilv 5y ago
> the directions said to code as you would professionally, and that means I should comment my work.
Were this a "professional" component/service, in perhaps the majority of situations today, he'd probably separate his docs into two kinds of documentation: the committed interface/API what, and the internal maintenance how.
The docstring for `print-translations`, for example, conflate these two kinds.
Incidentally, by 2000, Java had emphasized reuse API documentation for a few years, with how it presented Javadoc for both the core Java API and layered development, from the start.
By contrast, Lisp environments that exposed docstrings in IDE hypertext, like Emacs did, did some doc things better than Java for decades before, and are still really well-suited to army-of-one genetically-enhanced supersoldier Lisp hackers.
Enterprise development, SaaSes, microservices, large systems with multiple teams, etc., were arguably better off heading in the more software engineering direction that Java was going.
(Which is not to say that Lisps can't do the what&how docs separation. I've done a few embedded API docs things for Scheme and Racket that initially were inspired by Javadoc, Perl, and some of the less-commonly-used embedded docs setups for other languages. And have worked on a couple large Lisp systems that arguably wouldn't have been possible in a language without some of the Lisp family's other still-unusual strengths, nor without the highly-skilled developers that Lisps seem to attract disproportionately.)
- oalae5niMiel7qu 5y agoHunchentoot attempts to do the "what&how docs separation", but when I last used it, I had to look at the implementation to understand what my code was expected to do. At least Emacs and SLIME made it easy to pull up the source code.