この記事は、神戸電子専門学校 ゲーム技研部 Advent Calendar 2024の25日目の記事です。
はじめに
就活生の皆さん、ドキュメントについてご存じでしょうか。
絶賛就職活動中でソースコードを企業の方に見ていただく機会も増えてきたかと思います。
とはいえ企業側も時間は有限かつ応募されている数も多いので、基本的にはアピールしていた箇所を実装しているであろう部分を見るくらいしか時間を割けません。
そんな中説明ドキュメントを一緒に同梱していれば「この人は他の人と違い他人が見ることを考えれている」と興味を引け、よく見てもらえる可能性が上がるかもしれません。
一からドキュメントを作り上げるのは流石に時間がもったいないのでコメント規則だけ統一しておけば自動で作成できるDoxygenというツールの軽い紹介をやっていきたいと思います。
Doxygenを本格採用している使いまわそうと考えていたプロジェクトは販売を予定しているのでさすがにお見せするわけにはいかないので実際に使っていた就職活動作品を引っ張り出してきて改めて作り直したので紹介させていただきます。
セットアップ
良い記事を先人達がたくさん書かれているのでそちらを紹介させていただきます。
導入
設定
コメント規則
Doxygenの便利な要素
Doxygenには様々な機能があり、中でも
- 大量のクラスなどに概要を書いておいて一目で何をしているか纏めて見る側が全体を把握しやすくなる
- 呼び出し図などが見えて関係するものを事前にある程度知れる
- グループ分けができ○○関係などでまとめて見れる
といった点が使っていて便利でした。
コード/規則 サンプルコード
締めつけすぎても面倒すぎるので2,3個程度の規則をお勧めします。
例:
- ファイル説明は必須とする(必ず一番上に書かなければ認識されないので注意) @file,@brief
- 概要・注意点だけ必ず明記する @brief,@attention,@note
- バグ、todoは専用のコメントタグをきちんとつける @bug, @todo
extra
- カテゴリグループを作っておいてまとめる @defgroup,@ingroup
- 引数の想定している値を明記する @param
- 実装者/更新履歴を残す @author,@date
- サンプルコードを書いておく @code
// *****ファイル説明部分は必ず一番上に書くこと 一番上じゃないと認識されないです*****
/*!
* @file Example.h
* @brief 概要説明用。より詳細に語りたければ@detailsがいい。
// 以下必須ではない
* @author 制作者名。チームならお問い合わせがしやすくなって良い。
* @date 2412〇〇 アップデート情報やメモなど
* @date 2501〇〇 OOOのバグを修正
*/
#include<example>
/// @brief クラスの説明。クラスそのものの説明。大体ファイル説明と同じことを書くことにはなる。インテリセンスで表示されるのはこっちなのでそれを意識したことを書くといいかも
// 以下必須ではない
/// @details 詳細。必要であれば
/// @todo 〇〇の機能実装
/// @bug 〇〇のエラー確認 要修正
class ExampleClass
{
その他おすすめ グループ化
/// @defgroup Example グループ化定義 ドキュメント内topicにグループ名でまとめることができる。グループ化用ファイルを作ってまとめて列挙しておくと把握が楽でおすすめです。
/// @ingroup Example グループへの追加。ファイルから関数、変数など細部まで指定してグループにできるので便利。
最後に
いかがでしょうか。
人が見る前提でソースを書けているか見ている企業の方、まぁまぁいます。
自動でテンプレをポンと作ってくれる拡張機能もあったりするので楽しつつも
見やすいコードを書いていきましょう。
最後に私が関わっているチームの作品が発売を控えているのでぜひともウィッシュリストへの追加、購入のほどお願いいたします。
Discussion