javadocを書くべきか？

Question

eclipsを使っています。

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

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

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

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

---

JAVAソースの一番上には、どのようなJAVA DOC？もしくは、オリジナルの
編集履歴などを書いていますか？

Answer 1

書くべきと思います。

プロジェクト毎になんらかの規約があるとおもいます。
もしなければ 他の方の コーディング規約を参考にするとよいです。

• 例 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

Comments

[退会済みユーザー]

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

Answer 2

他の方の回答へのコメントにて

でもせっかくなので、機能概略、機能詳細、作成日、作成者、変更日、変更内容を書くべきですよね。

とありましたが、
機能概略、機能詳細を書くのはいいと思います。
作成日、作成者、変更日、変更内容はGit、SVN等のバージョン管理システムを導入しているのであればそちらで管理したほうがいいと私は思います。

Answer 3

＃既に十分な回答が出揃っていますが･･･

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

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

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

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

Answer 4

少し別の観点から。

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

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

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

Comments

[退会済みユーザー]

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

Answer 5

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

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

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

Comments

[退会済みユーザー]

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

Answer 6

実は、他のJava用コンポーネントを追加してから、作成したらいかがでしょうか。例えば私がいつも使っているFree Spire.Doc for Javaは相当いいです、無料ですし、試しても損もありません。ちなみに、関連のコードも紹介します：
Docドキュメントを作成するを例にします：

import com.spire.doc.documents.HorizontalAlignment;
import com.spire.doc.documents.Paragraph;
import com.spire.doc.documents.ParagraphStyle;

import java.awt.*;

public class CreateWordDocument {
    public static void main(String[] args){
        //ドキュメントインスタンスを作成する
        Document document = new Document();

        //セクションを追加する
        Section section = document.addSection();

       //セクションに3つの段落を追加する
        Paragraph para1 = section.addParagraph();
        para1.appendText("Spire.Doc for Java");

        Paragraph para2 = section.addParagraph();
        para2.appendText("Spire.Doc for Java is a professional Java Word API that enables Java applications " +
                "to create, convert, manipulate and print Word documents without using Microsoft Office.");

        Paragraph para3 = section.addParagraph();
        para3.appendText("A plenty of Word document processing tasks can be performed by Spire.Doc for Java, " +
                "such as create, read, edit, convert and print Word documents, insert image, add header and footer, " +
                "create table, add form field and mail merge field, add bookmark and watermark, add hyperlink, " +
                "set background color/image, add footnote and endnote, encrypt Word documents.");

        //段落1のタイトルスタイルを設定する
        ParagraphStyle style1 = new ParagraphStyle(document);
        style1.setName("titleStyle");
        style1.getCharacterFormat().setBold(true);
        style1.getCharacterFormat().setTextColor(Color.BLUE);
        style1.getCharacterFormat().setFontName("Arial");
        style1.getCharacterFormat().setFontSize(12f);
        document.getStyles().add(style1);
        para1.applyStyle("titleStyle");

        //段落2と3のスタイルを設定する
        ParagraphStyle style2 = new ParagraphStyle(document);
        style2.setName("paraStyle");
        style2.getCharacterFormat().setFontName("Arial");
        style2.getCharacterFormat().setFontSize(11f);
        document.getStyles().add(style2);
        para2.applyStyle("paraStyle");
        para3.applyStyle("paraStyle");

        //段落1を中央に水平に揃える
        para1.getFormat().setHorizontalAlignment(HorizontalAlignment.Center);

        //段落2と3の最初の行のインデントを設定する
        para2.getFormat().setFirstLineIndent(25f);
        para3.getFormat().setFirstLineIndent(25f);

        //段落1と2の後にスペースを設定する
        para1.getFormat().setAfterSpacing(15f);
        para2.getFormat().setAfterSpacing(10f);

        //ドキュメントを保存する
        document.saveToFile("Output.docx", FileFormat.Docx);
    }
}

以上です、お助けになるとさいわいです