質問をすることでしか得られない、回答やアドバイスがある。

15分調べてもわからないことは、質問しよう!

ただいまの
回答率

87.80%

javadocを書くべきか?

解決済

回答 5

投稿 編集

  • 評価
  • クリップ 0
  • VIEW 3,122
退会済みユーザー

退会済みユーザー

eclipsを使っています。

これも先輩から指摘がったのですが、

JAVAの関数の上には、JAVA DOCを書くべきだといわれましたが、
JAVAの規則では、確かに、そのようになっていると思います。

みなさんは、JAVA DOCを書いていますか?

Java docへは、どうやって、作成者、作成日、変更日、変更内容、を書いていますか?


------------------------------------

JAVAソースの一番上には、どのようなJAVA DOC?もしくは、オリジナルの
編集履歴などを書いていますか?
  • 気になる質問をクリップする

    クリップした質問は、後からいつでもマイページで確認できます。

    またクリップした質問に回答があった際、通知やメールを受け取ることができます。

    クリップを取り消します

  • 良い質問の評価を上げる

    以下のような質問は評価を上げましょう

    • 質問内容が明確
    • 自分も答えを知りたい
    • 質問者以外のユーザにも役立つ

    評価が高い質問は、TOPページの「注目」タブのフィードに表示されやすくなります。

    質問の評価を上げたことを取り消します

  • 評価を下げられる数の上限に達しました

    評価を下げることができません

    • 1日5回まで評価を下げられます
    • 1日に1ユーザに対して2回まで評価を下げられます

    質問の評価を下げる

    teratailでは下記のような質問を「具体的に困っていることがない質問」、「サイトポリシーに違反する質問」と定義し、推奨していません。

    • プログラミングに関係のない質問
    • やってほしいことだけを記載した丸投げの質問
    • 問題・課題が含まれていない質問
    • 意図的に内容が抹消された質問
    • 過去に投稿した質問と同じ内容の質問
    • 広告と受け取られるような投稿

    評価が下がると、TOPページの「アクティブ」「注目」タブのフィードに表示されにくくなります。

    質問の評価を下げたことを取り消します

    この機能は開放されていません

    評価を下げる条件を満たしてません

    評価を下げる理由を選択してください

    詳細な説明はこちら

    上記に当てはまらず、質問内容が明確になっていない質問には「情報の追加・修正依頼」機能からコメントをしてください。

    質問の評価を下げる機能の利用条件

    この機能を利用するためには、以下の事項を行う必要があります。

回答 5

checkベストアンサー

+2

書くべきと思います。

プロジェクト毎になんらかの規約があるとおもいます。
もしなければ 他の方の コーディング規約を参考にするとよいです。
- 例  GoogleのJavaコーディング規約 http://www.infoq.com/jp/news/2014/02/google-java-coding-standards

オープンソースでの実際のコメントの書き方もしらべると良いです。
- ant の場合 https://github.com/Uriziel47/ant/tree/trunk/src/main/org/apache/tools/ant
- maven の場合 https://github.com/apache/maven

次のページは参考になります。
- Javadoc ドキュメンテーションコメントの書き方 http://qiita.com/maku77/items/6410c67ce95e08d8d1bd

投稿

  • 回答の評価を上げる

    以下のような回答は評価を上げましょう

    • 正しい回答
    • わかりやすい回答
    • ためになる回答

    評価が高い回答ほどページの上位に表示されます。

  • 回答の評価を下げる

    下記のような回答は推奨されていません。

    • 間違っている回答
    • 質問の回答になっていない投稿
    • スパムや攻撃的な表現を用いた投稿

    評価を下げる際はその理由を明確に伝え、適切な回答に修正してもらいましょう。

  • 2015/07/24 09:03

    「Javadoc ドキュメンテーションコメントの書き方」は、参考になります。
    情報ありがとうございます。助かります。

    キャンセル

+2

他の方の回答へのコメントにて
でもせっかくなので、機能概略、機能詳細、作成日、作成者、変更日、変更内容を書くべきですよね。
とありましたが、
機能概略、機能詳細を書くのはいいと思います。
作成日、作成者、変更日、変更内容はGit、SVN等のバージョン管理システムを導入しているのであればそちらで管理したほうがいいと私は思います。

投稿

  • 回答の評価を上げる

    以下のような回答は評価を上げましょう

    • 正しい回答
    • わかりやすい回答
    • ためになる回答

    評価が高い回答ほどページの上位に表示されます。

  • 回答の評価を下げる

    下記のような回答は推奨されていません。

    • 間違っている回答
    • 質問の回答になっていない投稿
    • スパムや攻撃的な表現を用いた投稿

    評価を下げる際はその理由を明確に伝え、適切な回答に修正してもらいましょう。

+1

関数やソース等のについての資料は何かしらの方法で残すべきでしょうね。

今回の場合、先輩から指摘されたということなので、資料はjavadocから
生成していると思わるので、javadocを書くべきではないでしょうか...

Javadocの記載内容や方法は、それぞれ組織や部署毎にルールがあったり
しますので、先輩に聞くべきかと思います。

投稿

  • 回答の評価を上げる

    以下のような回答は評価を上げましょう

    • 正しい回答
    • わかりやすい回答
    • ためになる回答

    評価が高い回答ほどページの上位に表示されます。

  • 回答の評価を下げる

    下記のような回答は推奨されていません。

    • 間違っている回答
    • 質問の回答になっていない投稿
    • スパムや攻撃的な表現を用いた投稿

    評価を下げる際はその理由を明確に伝え、適切な回答に修正してもらいましょう。

  • 2015/07/24 09:07

    ルールは、聞きました。パラメータと戻り値だけあればいいそうです。
    でもせっかくなので、機能概略、機能詳細、作成日、作成者、変更日、変更内容を
    書くべきですよね。パラメータと戻り値は、変数名がとてもわかりやすし名前にしてありますし、ほぼ関数は、一画面に収まっているので、何をやっているか一目でわかるので、
    Java Doc書いてなかったんですが、戻り値も、boolenなのに。
    でも、Java Doc書きます。

    キャンセル

+1

少し別の観点から。


ライブラリーを公開する場合は、それを使用する人のためにJavadocを作成して公開するべきだと思いますので、この場合は必須と言えます。
最低でも、publicの要素には書いておくべきです。


プロジェクト内での共通クラスについても同様で、Javadocを作成して、プロジェクト内のどこかのサーバーにでもアップして読めるようにしておくのが良いと思います。


上記以外の場合は、プロジェクトのルール次第でしょうね。

投稿

  • 回答の評価を上げる

    以下のような回答は評価を上げましょう

    • 正しい回答
    • わかりやすい回答
    • ためになる回答

    評価が高い回答ほどページの上位に表示されます。

  • 回答の評価を下げる

    下記のような回答は推奨されていません。

    • 間違っている回答
    • 質問の回答になっていない投稿
    • スパムや攻撃的な表現を用いた投稿

    評価を下げる際はその理由を明確に伝え、適切な回答に修正してもらいましょう。

  • 2015/07/24 09:02

    そうですね、先輩から、Java docを入れるように言われたので、
    入れるしかないですね。

    キャンセル

+1

#既に十分な回答が出揃っていますが・・・

書くべきか? と問われれば、書くべき、というよりは、そもそも「書くことが前提」となっているようにも思います。

義務だから書くというスタンスも間違いではありませんが、今ついでに(詳細を忘れぬうちに)これこれの情報をこのフォーマットで記録しておくことで、自分含めた全ての開発者が後々どれほど楽が出来るか!? という観点で検討すると、楽しく効果的に「改善」に取り組めると思います。

適切なコメントの重要性はどの言語でも同じですが、デバッグにせよ機能追加にせよ、はたまたリファクタリングするにせよ、Javaほどクラス間の関連性を気に掛けなければならない言語も少ないように思います。

その際、Java Doc をどれだけ効果的に使えるかは、開発ツールの使い方や、引いては開発スタイルの問題であり、先ずそこから見直す方が結果的に早道かなぁ~って気もします。

投稿

  • 回答の評価を上げる

    以下のような回答は評価を上げましょう

    • 正しい回答
    • わかりやすい回答
    • ためになる回答

    評価が高い回答ほどページの上位に表示されます。

  • 回答の評価を下げる

    下記のような回答は推奨されていません。

    • 間違っている回答
    • 質問の回答になっていない投稿
    • スパムや攻撃的な表現を用いた投稿

    評価を下げる際はその理由を明確に伝え、適切な回答に修正してもらいましょう。

15分調べてもわからないことは、teratailで質問しよう!

  • ただいまの回答率 87.80%
  • 質問をまとめることで、思考を整理して素早く解決
  • テンプレート機能で、簡単に質問をまとめられる

関連した質問

同じタグがついた質問を見る