KDoc in a nutshell

「YUMEMI.apk #1」（2020年8月21日）での発表資料です。

Transcript

1. KDoc in a nutshell
   okuzawats
   YUMEMI.apk #1
   2020/08/21
   

   View Slide

2. 自己紹介
   okuzawats
   Twitter: okuzawats
   GitHub: okuzawats
   Androidアプリエンジニ
   ア @ フラー株式会社
   柏の葉キャンパス／新
   潟
   We are hiring!
   

   View Slide

3. KDoc is 何？
   

   View Slide

4. KDoc is 何？
   ドキュメンテーションコメントを書くやつ
   JavadocのKotlin版
   Markdown対応
   Dokkaによるドキュメントの自動生成
   自分はやったことないです

   View Slide

5. View Slide

6. 書き方
   https://kotlinlang.org/docs/reference/kotlin-doc.html
   

   View Slide

7. KDocを何で書くのか
   学習コストの低減
   自然言語で書けるので学習コストがあまりかからない
   新しくプロジェクトに入ってくる人
   一ヶ月後の自分
   設計品質の向上
   考慮漏れに気付くことができる
   設計の問題をあぶり出すことができる
   

   View Slide

8. KDocに何を書くのか
   仕様
   コードをどうやって使うのか
   なんでそうなっているのか
   コードを使う人がそのコードをどのように使うのかわかるように書く
   ドキュメンテーションコメントに従った実装を行う
   

   View Slide

9. KDocに何を書かないのか
   処理内容の翻訳
   読めばわかることをわざわざ書く必要はない
   邪魔になる
   Privateなメソッドに対するドキュメンテーションコメント
   外部に公開する物についてのみ書けば良い
   Privateなメソッドは普通のコメントで良い
   

   View Slide

10. まとめ
    ドキュメンテーションコメントを書こう
    

    View Slide

11. 参考文献
    Kotlin. (N.D.). Documenting Kotlin Code. Retrieved from
    https://kotlinlang.org/docs/reference/kotlin-doc.html
    佐藤竜一. (2009). エンジニアのためのJavadoc再入門講座.
    翔泳社.
    

    View Slide