注释不需要也不应当重复代码上已经不言自明的信息,做了什么,怎么做的,这些信息应该是由代码本身自描述的。
注释应当描述为什么要这样做,而非用别的方式,背后的考量点是什么,信息的来源是哪里等,从代码本身无法获知的信息。
避免使用注释生成工具,注释生成的原理,就是用代码本身已经存在的信息,以另一种格式或语言重新组织一遍。这只会提高信息的重复度,没有起到写注释应有的作用。
代码应该是自解释的,好的代码不需要写注释。
这一般只是自己懒得写注释的托辞。
/**
* get last updated time of this entity.
**/
val lastUpdated: Instant
/**
* Need to be updated to UTC now whenever any other fields of current object changes,
* In most cases, it is automatically updated by Spring Data.
*
* Is it primarily used for auditing and data syncing purpose,
* not expected to be used in any business oriented logic.
**/
val lastUpdated: Instant
不要放行尾
val lastUpdated: Instant // get last updated time of this entity.
字段注释与行注释都有特定的定法
// get last updated time of this entity.
val lastUpdated: Instant
字段、方法的注释,有特定的格式要求。一方面可以用于生成API文档,另一方面也可以用于IDE的代码提示。
/**
* Gets last updated time of this entity.
* @return: Instant value in UTC.
**/
val lastUpdated: Instant
大家都用//TODO:
,就不要自己创造一个***Something to be done***
表达同样的意思。
// ***Something to be done***: Use Instant instead of String
val lastUpdated: String
除非能推广到全公司
// TODO: String as it is has a customized format, but ISO-8601 should be used.
val lastUpdated: String