Education Ecosystem Blog

コードの文書化を支援するツールは、時代のニーズであると言えます。 コード ドキュメンテーションは、プログラマーが自分のコードを文書化するプロセスです。 エンジニアの間ではよく知られた用語です。

多くのプログラマはコード ドキュメンテーションに困惑しているようで、できるだけ逃れようとしています。 コードドキュメントを書く目的がないため、コードの可読性が悪くなり、他のチームメンバーのメンテナンスが大変になります。

コードドキュメントはプロジェクトドキュメントとは異なり、主にシステムがどのように動作するのかを目的としています。 コード ドキュメントを書く理由は複数あるにもかかわらず、多くのプログラマーはそれを省略する傾向があります。 もしあなたがコードを文書化しないコーダーの 1 人であるなら、ドキュメントを書くべき理由をチェックしてください！

• 時間が経てば、自分のコードに戻るでしょう。 後で悔やむより、今コード ドキュメントを書いたほうがよいのです。

• 自分のコードをチームの他のプログラマーがメンテナンスして使用できるようにしたい。 コードのメンテナンスは、文書化されていないと大きな問題になります。

• オープンソースやその他のコラボレーションを通じて、他の人に助けてもらう必要があります。 大きなコラボレーションを考えているなら、今すぐコードのドキュメント化を始めましょう！

• • より良いコーダーになりたいあなたへ。 コードを文書化することで、ロジック
    をより明確にすることができます。 また、コード ドキュメントを書く習慣は、あなたのコードをより良くします。

• コード ドキュメントを書くことは、あなたの書く能力を向上します。

上記のすべての利点があっても、全体として、ドキュメントは時間のかかるプロセスです。 より速いドキュメント化プロセスとスタイルの一貫性を可能にするために、コード ドキュメンテーション ツールを使用する必要があります。 さっそく始めましょう。

1. LiveEdu

これを読んでいる人は、ソーシャル プロジェクトの放送がコード ドキュメントのためのツールになるとはどういうことか考えていることでしょう。 その答えは、「ビデオ・コード・ドキュメンテーション」という言葉にあります。
あなたは、プロジェクトの作業を直接Livecodingで放送したり保存したりすることができます。 こうすることで、チームメンバーがプロジェクトの重要なセクションに簡単にアクセスできるようになります。 コードを文書化するためのツールとしてLivecodingを使用すると、複数の利点があります。 そのいくつかを以下に紹介します。

Video documentation benefits in the nutshell

1. 1. それは純粋なテキスト文書による文書を強化し、読み手に優れたコンテキストと理解を提供するものである。

1. 1. Agile チームは、プロジェクトの変更を簡単に追跡できます。

1. テクニカル ライターは、プロジェクトの理解を深めるためにビデオ コード ドキュメントを使用することができます。

Damian Wolf が書いた壮大な作品「Why Developers Write Horrible Documentation and How to Solve It」を読んで、この考えをよりよく理解してください。

Doxygen

Doxygen はソースコードから文書を生成するための素晴らしいツールです。 このツールは C++ を対象としていますが、PHP、Java、Python などでも使用可能です。 Doxygen の助けを借りて、オンライン HTML ドキュメントを作成することができます。 また、Unix man ページ、PostScript などの複数のフォーマットで出力を生成するために使用できます。

Doxygen を使用する最大の利点は、ソース コード ドキュメント全体に一貫性を持たせることができることです。 また、ドキュメント化されていないソース ファイルを使用してコード構造を生成するのに役立ちます。 必要なのは、適宜設定することだけです。

Edurolp はスペインのコルドバ出身で、彼のコードを文書化するために Doxygen を使用しています! ここでストリームをチェックしてください。

Sphinx

Sphinx はプログラマに人気のあるドキュメント作成ツールです。 BSDライセンスのもとで利用可能で、Python、C、C++といった複数のプログラミング言語をサポートしています。 Sphinx は、彼らのドキュメントを整理したい開発者にとって理想的です。 プロジェクトのドキュメントとコードのドキュメンテーションの両方に使用することができます。 Sphinxの特徴としては、豊富な相互参照、複数の出力形式、自動インデックス、拡張機能サポートなどがあります。

4. Pandoc

Pandoc は、そこにある他のコード文書化ツールとは違います。 それはスイスアーミーナイフのように振る舞い、開発者があるマークアップ形式を別のものに素早く変換することを可能にします。 マークアップで自分のコードドキュメントを書くのが好きで、すぐに他のフォーマットに変換したい場合、Pandoc はあなたのためのものです。 テキスタイル、reStrcuturedText、LaTex、ePUB など、幅広いドキュメントをサポートしています。

さらに、定義リスト、表、脚注など、複数のマークダウン構文拡張を提供します。 サポートされている拡張機能とドキュメントフォーマットの完全なリストは、公式ページをチェックしてください。

5. Dr. Explain

フロントエンドの開発にも、ある程度はドキュメントが必要です。 そのようなツールの1つである Dr. Explain は、アプリのユーザーインターフェイスを文書化することができます。 これは、主要なインターフェイス要素をフィルタリングし、各要素について関連するメタ情報を抽出します。 一度行えば、抽出された情報を修正し、素早くインターフェイスのドキュメントを作成することができます。 LaTex

LaTex は科学的なプロジェクトを文書化するためのデファクトスタンダードです。 しかし、コードやプロジェクトのドキュメントを含む他の種類のプロジェクトにも活用できます。 そのようなユーザーの一人、メキシコ、Monterrery の dcelisgarza は、数学的コードの文書化における LaTex の有用性を示しています。 ここでチェックしてみてください！

LaTex は、科学技術文書の作成に焦点を当てた高品質のタイプセットシステムとしてよく知られています。

7. Markdown

Markdown は、John Gruber が生み出した、高品質のコードやプロジェクト・ドキュメントを書くのに役立つシンプルな言語です。 技術的には、MarkdownはウェブライターのためのテキストからHTMLへのツールですが、それは同様にドキュメンテーションの目的のために使用することができます。 開発者として、あなたはMarkdownでドキュメントを書き、後でPandocを使ってそれを好きなフォーマットに変換することができます！

Checkout AbiAbdallahAwad using Markdown to document APIs in RAML here.

8. GhostDoc

GhostDoc, a Visual Studio extensionで、XMLドキュメントのコメントを簡単に生成することができます。 このツールは、名前、パラメータ、文脈情報、タイプなど、複数の要因に基づいてコメントを生成します。

9. Natural Docs

Natural Docs は、多くのプログラミング言語で動作する、さらに別のオープンソースのドキュメントジェネレータです。 これは、コードドキュメントの生成を自動化し、それをHTML形式に変換するのに役立ちます。 現在、Natural Docs は、Python、C++、PL/SQL、Actionscript などを含む 19 の言語をサポートしています。 phpDocumentor

If you are a PHP developer and want to generate code documentation from the source code, look no further than phpDocumentor. phpDocumentor はコード文書を扱う独自の方法で、正しい文書への参照として機能します。 phpDocumentor の主な機能は、PHP フレームワークのサポート、プラグイン・アーキテクチャなどです。 内部の仕事は、強力で柔軟なテンプレートシステムによって管理されます。 このツールは、レポートやグラフを生成し、全体的なコードの品質を高めるのにも役立ちます。

Bonus: Doc-O-Matic は、コードドキュメントを生成するための有償ソフトウェアです。 詳しくはこちらをご覧ください。

まとめ

本日は、完璧なコード ドキュメントを作成するための 10 のツールを見てきました。 上記のツールは、ドキュメント化プロセスの補助として機能することに留意してください。 適切なドキュメンテーションは依然として必要であり、無視すべきではありません。