Inline vs. External Docs for your Code

internal-external-docs.md

Inline vs. External Docs for your Code

I'm pro external, heres why...

Pros of external

• Make code messy
• Not maintained well, example Bob adds a new argument but never updates the docs.
• Often not useful, example: // returns monkey whereas if your actually writing docs you put more thought into it
• Examples and usage code is easier to read
• Often more like 'docs' instead of 'specs'

Cons of external

• Harder to maintain since its not right in front of you when you are making changes
• Code examples have to be explicit since code isn't right in front of you