LinkORB Engineering

Rules in [#databases]

Database commenting guidelines


Rule: Avoid redundant comments if field details are evident

Rationale: Refrain from including information in descriptions that are available in another form. For example, in the name of the field, its relation, in a dev pattern, etc. If you can ascertain a field's meaning solely based on those elements, omit the comment altogether.


The redundant comment is removed.

+--------+----------+---------+
| column | type     | comment |
+--------+----------+---------+
| id     | integer* |         |
+--------+----------+---------+

Auto Increment is used on all tables, so the Primary Key (PK) indication with an asterisk is unnecessary.

+--------+----------+---------------------+
| column | type     | comment             |
+--------+----------+---------------------+
| id     | integer* | Autoincrementing PK |
|        |          |                     |
|        |          |                     |
|        |          |                     |
+--------+----------+---------------------+

Rule: Exclude system behavior from database comments

Rationale: If a behavioral description of the main functions of the system exists, and as such, it includes fields used in this behavior, then this information should not be in the database comment.

Rule: Include information not available to the reader

Rationale: In case we have situations where the reader of the documentation doesn't have access to the code or extra documentation and relies solely on the database description, then the information should be made available in the database description (field or table, whichever fits better).

Rule: Enum and Categorical Field Comment Guidelines

Rationale: The following sub-rules apply to enums and enum-like/categorical fields:

  1. In cases where the field is an enum, and it is possible to see the values, then the comment is not necessary;
  2. In cases where the field is a string but is a backed enum, for example, then a comment is not necessary;
  3. In the case where the field is a string and is a soft enum like a field status that only has four states, then we should document it.

+------------+--------+----------------------------------------------------+
| column     | type   | comment                                            |
+------------+--------+----------------------------------------------------+
| event_type | string | 'Status update' reflects operational               |
|            |        | changes or software updates. 'Performance metric'  |
|            |        | pertains to monitoring system or application       |
|            |        | performance, including response times and          |
|            |        | resource usage.                                    |
+------------+--------+----------------------------------------------------+

Case 3 applies: a soft enum with two values. The values should be defined.

+------------+--------+--------------------+
| column     | type   | comment            |
+------------+--------+--------------------+
| event_type | string | Specifies the type |
|            |        | of event.          |
|            |        |                    |
+------------+--------+--------------------+

Rule: Prefer clear column names over explanatory comments

Rationale: In cases where a column name is ambiguous, it's often better to rename the field to provide clarity rather than relying on comments to explain its meaning.


Field renamed so comment is not needed.

+----------------+----------+
| column         | type     |
+----------------+----------+
| scheduled_date | datetime |
|                |          |
+----------------+----------+

"At" implies when the study was scheduled, not the scheduled date.

+--------------+----------+-----------------------+
| column       | type     | comment               |
+--------------+----------+-----------------------+
| scheduled_at | datetime | Scheduled date and    |
|              |          | time of a particular  |
|              |          | study.                |
+--------------+----------+-----------------------+

Rule: Adapt database comments to specific database requirements

Rationale: If these situations outlined in the other rules are conditional to some databases, then individual databases might have different types/qualities of comments. Hence, it is crucial to evaluate the rules applicable to each database at an individual database level.

About Databases
  • Name: Databases (#databases)