見出し画像

MGL週報 #40 - 文章作成の勧め

Acerola

このエントリはゲーム開発用フレームワーク「MGL」の開発記録です。MGLはzlibライセンスの下に無償で提供されています。


今週の作業内容

ByteStreamのAPIリファレンスの作成

まず「ByteStreamって何？」というところから説明が必要ですね。これはメモリ上のバッファをバイト単位で連続して読み書きするためのクラスです。MGLの最初期の頃から、もっと言うとMGLの前身となったライブラリの時代から存在するもので、簡単に言うとデータの塊を作ったり読み込んだするのにあると便利なクラスです。

何で今このタイミングでこのAPIリファレンスを作成しているのかというと、セーブデータの読み書きに使用するためです。MGLにはファイル入出力のAPIを使用せずともセーブデータを取り扱うための仕組みが存在しており、そのインターフェースとしてこのByteStreamが使われているのです。今回セーブデータまわりのドキュメントの作成も行う予定でして、そこで必ず必要になるよねという事で今更作成しています。

APIリファレンスはおおよそ書き上げてあるのですが、いくつか修正点が炙り出されているため、その対処後に再編集する作業が残っています。という訳で、次項へ。

ByteStreamの改修

APIリファレンスを書いていて気付いた問題点などの対処です。ほぼ細かい問題なのですが、1つだけ真面目に考えないといけない問題がありまして、それがエラー発生後の挙動です。

ByteStreamは初期化時にメモリ領域を受けて、その内容を読み書きするためのクラスです。その安全策として、管理している領域外へのアクセスを検出し、安全に処理を失敗させるようになっています。いわゆるバッファオーバーフローへの対策です。

で、リファレンスを書きながら気付いたのは、オーバーフロー発生時やその後の挙動がいまいち統一されていないという事。オーバーフローそのものは抑制されているため致命的な問題に直結するものではないものの、インターフェースの不統一は他の不具合を誘発するリスクがあります。特に、外部ファイルの解析などに使われやすい性質上、それが原因でセキュリティーホールになる何て事も……まあ、可能性は低いですが、全く無い話ではありません。

真面目にと言っても綿密な設計と十分な動作検証を要するほどではないものの、ちゃんと考えておくに越した事はないよね、という感じの問題です。

あと、オーバーフロー発生時に例外を投げるインターフェースも欲しいなと思ったり。ファイルの入出力はちゃんと分かれているのですが、こっちはそこまで考えていませんでした。

文章作成の勧め

普段からしつこいくらい述べていますが、ドキュメント化は大切です。誰かに読んでもらう事や、大切な情報を脳みその外側に置いておく事はもちろん大切ですが、何よりその内容に再び向かい合う機会としての効果が大きいです。

今回のByteStreamの件などは格好の例でしょう。何年も前から使い続けている小規模なクラスでさえ、ちゃんと説明しようとして初めて気付く問題が炙り出されるものなのです。

また、何かを説明する際に「説明がめんどくさいな」とか「ややこしくて上手く文章化しにくいな」と感じる事は多々あります。ドキュメント化の最中にこれに遭遇した場合は黄色信号です。作り手であり書き手でもある本人がそう思うのなら、読み手（使い手）はより強くそう思うはずですから。

そして、その対処は文章を練り直す事よりも、説明しようとしている事そのものを見直す事をお勧めします。説明しにくいという事は、設計や実装に問題がある可能性が高いためです。例えば何か扱いに注意を要するものがあったとして、その注意点を文章で説明するよりも、直しちゃった方が早いなんて事は多々あります。アメリカの詩人ロングフェローさんも似たような事を述べています。「間違った事の言い訳をするより、正しい事をした方が早い」です。

要するに、文章作成には書き手にもメリットが大きいですよ、というお話です。文章を書くという行為は「誰が読んでくれるのか？」とか「役に立つ情報なのか？」といった読み手側の事ばかりを考えがちですが、それを理由に書かないという結論に達してしまうのは勿体無い話です。もちろん、読み手の事を考えて文章を書く事は大切ですが、そういった文章力を磨くのにも役に立つのではないでしょうか？ 文章力というスキル、ゲーム開発でも地味に重要ですからね。

その他

本当は今週はSteamのコントローラ対応の件についてお話する予定だったのですが、色々と準備が足らずに後回しにすることにしました。

ここ最近、平日に作業時間がほとんど取れていなくて、凝った内容をなかなか書き上げられないのですよね。先週の週報をiPadで書いたのは僅かな時間も活用するための試みでしたが、扱う内容的に色々な情報を参照しながら書くので、環境が整っていないと難しという結論に達しました。

この記事が気に入ったらサポートをしてみませんか？