ソースコードの見やすさを考える

2021年9月8日

僕はソースコードの見やすさの一つとしてパターン化があると考えています。
もちろんコメントも重要なファクターですが、それもパターン化されている上でのことです。

そのためにはひな形があるととても便利です。
今回は僕がいつもつかっているひな形を紹介します。
ひな形はドキュメント生成ツールDoxgenに対応していますので、簡単にドキュメント化も可能です。

ひな形ソースコード

解説

後ほど解説する予定ですが、ドキュメント生成ツール「Doxgen」に対応した形でソースコードのひな形を作成しています。
Doxgen形式にするメリットはもちろんドキュメントを自動生成出来ることもありますが、
ソースコードの形式が同一になり、多人数のプロジェクトで開発する際に人のソースコードが読みやすくなることが最大のメリットだと思います。

ソースヘッダ

ソースファイルの先頭に入れるコメントです。

ファイル全体の説明を簡潔に記述します。
概要は以下のように記述すると良いでしょう

簡単に説明すると上から
@file ソースファイル名
@brief このソースファイルの説明
@author 著者
@data 作成日
@aar 修正履歴の記入

インクルード

ヘッダの下にインクルード文をまとめます。
特に説明はいりませんね。

クラス/構造体

クラスは関数本体と同一のファイルに記述する必要はありません。
特に大きいクラスは○○.hとして別のファイルに記述した方が可読性が上がります。
僕はクラスに記述するメソッドは、クラス内に記述する方法を進めています。
プロトタイプのみ記述して別ファイルに記載する方法もありますが、
複数のファイルを閲覧する必要があり、ソースコードが追いにくくなります。
クラス内に記述するとメソッド数が多すぎて可読性が落ちるとおっしゃる方もいますが、
その場合クラス設計に問題があることが多いと思います。
以前、1万行を超えるクラスを見たことがあります、これは極端ですが1000行を超えるようなら
見直してみる価値はありそうです。
関数のコメントの書き方は、次の関数説明をごらんになって下さい。

関数

ヘッダ部は、ほぼファイルのヘッダと同様の記述です。
@noteは関数を使う上で注意しなければならないことなどを記述すると良いでしょう。

引数の説明に関しては上のヘッダ内では無く、引数に直接コメントしています。
これは直感的に見やすいことと、引数の追加や削除などが発生した場合に
ヘッダ内だと変更忘れが発生しやすいためです。

尚、引数の先頭に「,」を打つのは僕の趣味ですが引数の追加/削除で少々やりやすいためです。

スコープ

関数の記述はスコープを意識しましょう。
先頭にstaticを付けることでファイル内のみ有効な関数名であることを示し、他のファイルに同一の関数名があっても問題ありません。
staticを付けないとファイルを超えて全体で有効になります。
ファイル内で自分の位置より後ろに存在する関数は最初にプロトタイプを宣言する必要があり少々面倒なので、

呼び出し先関数
呼び出し元関数

のように記述した方が楽だと思います。

最後に

関数テンプレートを準備することで、ソースコードの形式が一定化し見やすいソースコードを作成することが出来ます。
特にプロジェクトで多人数開発では効果を発揮すると思います。