Blog: December 2017

Most of these posts were originally posted somewhere else and link to the originals. While this blog is not set up for comments, the original locations generally are, and I welcome comments there. Sorry for the inconvenience.

How can a non-programmer document database behavior?

Someone asked a question on the SE site for software engineering. Paraphrasing (to avoid violating the license): this person, a non-programmer, uses RDBMS tables populated by code from the team, and is looking for a way to document the "contracts". For example, a table of account changes records only ones that took effect, not all attempts; where would one document that? Or, there's a job that affects accounts that have not been changed in N days; does that mean exactly N days, down to the minute, or just the dates? Thus far this person has had to ask the developers who wrote the code; adding documentation could help the next person who comes along.

This is the answer I posted:

In general, the closer documentation is to the code that it documents, the more likely it is to stay correct over time. This is one reason that auto-generated reference documentation like Javadoc and Doxygen works better than externally-written reference documentation: the usage syntax that generated documentation shows is by definition always correct (drawn straight from the code), and the comments are right next to the declarations in the code so there's a better chance that somebody editing the code to change the interface will see and (we hope) update the comment. Read moreā€¦