Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add 'Trash in, Treasure out' blog post #2573

Merged
merged 13 commits into from
Dec 6, 2024
Prev Previous commit
Next Next commit
Refer to title
hdoordt committed Dec 6, 2024

Verified

This commit was signed with the committer’s verified signature.
hdoordt Henk Oordt
commit f8c2d7affbdf5a29171b526162ed53d83dc3b182
11 changes: 6 additions & 5 deletions src/posts/2024-12-02-trash-in-treasure-out.md
Original file line number Diff line number Diff line change
@@ -27,11 +27,12 @@ user of the code's API, the colleague refactoring the codebase, and new
developers are on the same page about the _intent_ and _invariants_ of that
code. What is this code doing? How am I supposed to use it correctly? What
happens if I mess up? How do I protect this API from input it might choke on?
Traditionally, one would write in documentation and code comments the answers
to these and many other questions. Writing documentation is a very valuable
job, but sadly, developers are human. And humans make mistakes. And if the
humans think they _themselves_ don't make mistakes, they will surely agree
that their colleagues _do_.
Because 'Garbage in, garbage out' is not a great philosophy when setting up
critical and robust systems. Traditionally, one would write in documentation and
code comments the answers to these and many other questions. Writing
documentation is a very valuable job, but sadly, developers are human. And
humans make mistakes. And if the humans think they _themselves_ don't make
mistakes, they will surely agree that their colleagues _do_.

Documentation written in human language needs to be clear, specific, and up-to-
date. And even if it's written well, for it to do its job, documentation needs