Skip to content

24 ways to impress your friends

Vote up?

Ryan Fitzer

PAUL BENJAMIN IRISH:

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.