Guide to Adding Comments to Tables and Columns When Automatically Generating Entities Using ORM in…

Overview

This document provides a guide on how to add comments to tables and columns when automatically generating entities using ORM in Java backend development.

Problem

• While developers can understand the meaning of columns through annotations, data engineers must manually check the source code or ask the developer, which can be inconvenient.
• When using annotations and column comments together, there can be issues with framework dependency, decreased efficiency, and human error.

Solution

• Use the comment attribute introduced in JPA 3.2 to add comments to tables and columns.
• Utilize both Hibernate’s @Comment annotation and JPA 3.2's comment attribute to enable automatic refactoring for future version upgrades.

Key Points

1. JPA 3.2’s comment attribute
   • The comment attribute was added to table and column annotations starting from JPA 3.2.
   • This attribute allows you to directly specify descriptions for tables and columns.
2. Hibernate @Comment annotation
   • The @Comment annotation provided by Hibernate can be used to add descriptions to columns.
   • This is useful in environments that do not support JPA 3.2.
3. Automatic refactoring for future version upgrades
   • Tools like OpenRewrite can be used to automatically convert Hibernate @Comment annotations to JPA 3.2's comment attribute.
   • This allows for easy code upgrades when Spring Data JPA and Hibernate’s JPA 3.2 versions are supported in the future.

Code Examples

JPA 3.1 + Hibernate

@Column  
@Comment(value = "Is locked")a  
private boolean accountNonLocked = true;

JPA 3.2

@Column(comment = "Is locked")  
private boolean accountNonLocked = true;

References

• Jakarta Persistence™ 3.2
• Migrate to JPA 3.2
• OpenRewrite