3 ms·

I add my comments to the commit message that contain the schema changes. If you seriously add a comment like 'required first name of user' you are wasting every

by NDizzle 11y ago

I add my comments to the commit message that contain the schema changes. If you seriously add a comment like 'required first name of user' you are wasting everyone's time.

e12e 11y ago
> I add my comments to the commit message that contain the schema changes. You're adding the information in "git diff" for the .sql-files for the commit to the comment?
- NDizzle 11y ago
  I have a repo for SQL changes that include synchronization files (.sql) for all of the changes I made. The diff does include a summary of the changes. Unfortunately, it does not include any information about what the last_name field does.
otherusername2 11y ago
Yes, that would be a waste of time. But in the past I've gotten in the habit of commenting things in the database for larger projects, and have written a bunch of tools to extract those comments and generate database documentation from it. For large databases (table-wise, not data-wise), it's been absolutely invaluable to be able to just take the DB docs and reason about how stuff works in there. "Oh, this table is fed by a trigger from table X!", "Ah, the `system` table contains non-tenant specific global system settings". Stuff like that. Yeah, in a perfect world everything in a database would be obvious from its name, but this is not a perfect world and naming things properly is extremely hard.
jsnell 11y ago
Especially when at least right now one of the things being documented in the example as "first name of the user" is the last_name field! last_name | character varying(50) | ... | required first name of user That shows two documentation antipatterns, actually. Documentation that conflicts with the code, and documentation so generic that it gets carelessly filled in with copy-paste.
- cmdkeen 11y ago
  I work with Oracle these days, or the ... might contain it - but is it not also missing a NOT NULL constraint? Documentation that conflicts with the DDL makes for an easy code review at least. I look at it more like an interface specification, especially as there are several ways to write DDL - though there should really be a house style. For instance the NOT NULL constraint might be being added later on the script, so it isn't necessarily readable in the same way as normal code.

by NDizzle 11y ago

I add my comments to the commit message that contain the schema changes. If you seriously add a comment like 'required first name of user' you are wasting everyone's time.

e12e 11y ago

> I add my comments to the commit message that contain the schema changes. You're adding the information in "git diff" for the .sql-files for the commit to the comment?

NDizzle 11y ago
I have a repo for SQL changes that include synchronization files (.sql) for all of the changes I made. The diff does include a summary of the changes. Unfortunately, it does not include any information about what the last_name field does.

otherusername2 11y ago

Yes, that would be a waste of time. But in the past I've gotten in the habit of commenting things in the database for larger projects, and have written a bunch of tools to extract those comments and generate database documentation from it. For large databases (table-wise, not data-wise), it's been absolutely invaluable to be able to just take the DB docs and reason about how stuff works in there. "Oh, this table is fed by a trigger from table X!", "Ah, the `system` table contains non-tenant specific global system settings". Stuff like that. Yeah, in a perfect world everything in a database would be obvious from its name, but this is not a perfect world and naming things properly is extremely hard.

jsnell 11y ago

Especially when at least right now one of the things being documented in the example as "first name of the user" is the last_name field! last_name | character varying(50) | ... | required first name of user That shows two documentation antipatterns, actually. Documentation that conflicts with the code, and documentation so generic that it gets carelessly filled in with copy-paste.

cmdkeen 11y ago
I work with Oracle these days, or the ... might contain it - but is it not also missing a NOT NULL constraint? Documentation that conflicts with the DDL makes for an easy code review at least. I look at it more like an interface specification, especially as there are several ways to write DDL - though there should really be a house style. For instance the NOT NULL constraint might be being added later on the script, so it isn't necessarily readable in the same way as normal code.