I think APIs should be documented in HTML/Markdown/Wiki. It keeps the code clean and gives you plenty of flexibility to add examples, videos, whatever.
This makes great sense, but I find that having inline doc comments allows for easier maintenance. Since the doc comment is easily accessed, I’m more willing to update it as I update the codebase.
Even with this ease, it’s hard to switch gears from formal logic to articulation. The author’s suggestion of writing first and coding second would help this issue.
Ryan Fitzer
PAUL BENJAMIN IRISH:
This makes great sense, but I find that having inline doc comments allows for easier maintenance. Since the doc comment is easily accessed, I’m more willing to update it as I update the codebase.
Even with this ease, it’s hard to switch gears from formal logic to articulation. The author’s suggestion of writing first and coding second would help this issue.