取り扱いに注意の必要なメソッドがあったとします。
その注意喚起のため、コメントを書くだけでは対策として不十分です。
/**
* このメソッドは取り扱いに注意が必要です
*/
fun sensitiveMethod() {
// とっても注意が必要な処理
}
利用箇所には上記のコメントが現れませんので、実装者がソースコードを追って確認しなければ気づけません。実装者が気づけない場合、レビュワーが気づくのはさらに難易度が高く、見逃されてしまいかねません。ライブラリの場合はソースコードが利用者の手元にない可能性もあります。
fun hoge() {
sensitiveMethod()
}
そんな場合に、アノテーションによるOptInを強制する手段がKotlinに用意されています。@RequiresOptInというアノテーションを付与したアノテーションを定義します。
@RequiresOptIn(level = RequiresOptIn.Level.ERROR)
@Retention(AnnotationRetention.BINARY)
@Target(AnnotationTarget.FUNCTION)
annotation class VerySensitiveApi
ここでは、levelをERRORにしています。こうすると、OptInしていなければコンパイルエラーになります。エラーまでは不要で、警告を出したい場合はWARNINGを指定します。
後はアノテーション共通ですが、@RetentionをBINARYにして、ライブラリになってもアノテーションが保持されるようにして、@Targetで作成するアノテーションを付与する対象を指定します。これらは利用局面に応じて適宜変更してください。
これで、VerySensitiveApiというアノテーションを定義できました。あとは注意が必要なメソッドに、このアノテーションを付与します。
/**
* このメソッドは取り扱いに注意が必要です
*/
@VerySensitiveApi
fun sensitiveMethod() {
// とっても注意が必要な処理
}
そうすると、利用箇所では
fun foo() {
sensitiveMethod()
}
と、単純に呼び出すとコンパイルエラーとなります。
利用するには以下のように、明示的に@OptInアノテーションで利用を宣言しなければいけません。
@OptIn(VerySensitiveApi::class)
fun bar() {
sensitiveMethod()
}
これで実装者は少なくともOptInが必要なメソッドであるとして気がつきドキュメントなどを調べるでしょうし、レビュワーも、アノテーションがついていることで気づきやすくなりますね。
また、@RequiresOptInではメッセージを指定することもできますので、
@RequiresOptIn(
message = "このメソッドはとっても注意が必要なので、使うときは設計レビューを通して承認を受けてください。",
level = RequiresOptIn.Level.ERROR,
)
@Retention(AnnotationRetention.BINARY)
@Target(AnnotationTarget.FUNCTION)
annotation class VerySensitiveApi
などと書いておくと、IDEでそのメッセージを確認したり、ビルド時のエラーログにもこのメッセージが表示されるようになるので、より詳細な情報を付与することもできます。
以上です。