search

Police-Data-Accessibility-Project / data-sources-app

An API and UI for using and maintaining the Data Sources database
MIT License
2 stars 5 forks source link

Add comments to PDAP PostgreSQL tables #225

Open maxachis opened 5 months ago

maxachis commented 5 months ago

Tables such as AGENCIES in the PDAP server are generally self-explanatory with column names. However, some columns, such as count_data_sources or defunct_year, are not immediately clear as to their purpose -- while I might be able to generally infer the meaning of these columns by looking at the context of other columns and the data within, there is a degree of ambiguity and friction that slows me down in comprehending the table, and would likely slow down other developers.

PostgreSQL enables adding comments to columns and tables, either through interfaces such as PGAdmin, or through scripts such as the below:

COMMENT ON TABLE customer_orders IS 'Stores all customer orders, including order details and status.';
COMMENT ON COLUMN customer_orders.order_date IS 'The date and time when the order was placed.';

This would be a fairly easy way to add context to the columns and make the code more self-documenting.

maxachis commented 5 months ago

Additionally, unclear if this is the best issue to put this in, but since we don't have a repository dealing with the database specifically (and the meta repository is very quiet), I figured this was one of the better ones to put this issue in.

josh-chamberlain commented 4 months ago

@maxachis what do you think about moving these data dictionaries? I made an issue earlier which might actually stand in for this one, sorry I didn't see yours first: https://github.com/Police-Data-Accessibility-Project/docs/issues/13

also, this repo is fine, since that's where the code will live! we have options for organizing it on the roadmap project.

Image

maxachis commented 4 months ago

@maxachis what do you think about moving these data dictionaries? I made an issue earlier which might actually stand in for this one, sorry I didn't see yours first: Police-Data-Accessibility-Project/docs#13

I think that migrating the data dictionaries on the SQL tables so that they are defined in the SQL tables themselves is probably the best course of action. There may even being a way of pulling that data so that it can be displayed in an external docs document, which is not necessary and would add additional components to develop/maintain, but would allow us to retain visibility outside of the database itself.

We could also set up code that regularly checks to see if tables have properly identifying comments, if we wish to enforce documentation on the tables.

josh-chamberlain commented 4 months ago

@maxachis I think the data dictionary still needs to exist as a standalone resource for non-developers to understand and use our app/data. Telling a dev to reference the data dictionary is easier than telling a non-dev to check the SQL table, if that makes sense. I'll still keep docs#13, and adding SQL comments is still OK by me