$30 off During Our Annual Pro Sale. View Details »

KDoc in a nutshell

okuzawats
August 21, 2020

KDoc in a nutshell

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

okuzawats

August 21, 2020
Tweet

More Decks by okuzawats

Other Decks in Programming

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