Entity Relationship Diagrams

Draw it before you build it. A box per entity, a line per relationship, and the cardinality marked at each end. It takes ten minutes and it is the cheapest place to discover that two things you thought were separate are the same thing, or that a relationship you assumed was many-to-one is not.

Keep it in the repository next to the schema and update it when the schema changes. A diagram that disagrees with the database is worse than none, because somebody will trust it.

What a good diagram shows. Entities, their key attributes, the relationships and their cardinality, and which side owns the foreign key.

What it should not try to show: every column, every index, every constraint. That is what the schema is for. The diagram is for the shape, and a diagram nobody can take in at a glance has stopped doing its job.