DRY コードによる作業時間の短縮と手直しの削減

プログラマーには、コードを単純化して重複を減らすための DRY (Don't Repeat Yourself : 繰り返しを避ける) という格言があります。このアドバイスは、頻繁に使用する小さなコードを、複数の場所で取り込むことができる別のファイル内に単一ソース化することを促すためのものです。DRY 原則に従うことで、複数の場所での変更にかかる時間を短縮し、ミスを減らすことができます。

実は、私が所属する Fastly のドキュメントチームにとってもこのアドバイスが有効であることが分かりました。私たちはさまざまなドキュメントの中で特定の文章やフレーズを何十回も使用していますが、それらのフレーズを一つの場所にまとめ、複数のガイドで参照できるようにすると便利であることに気づきました。こうすることで、ドキュメントの標準化、コピー＆ペーストによるミスの削減、インターフェースの変更によるドキュメントの更新に伴う問題の一部を解消することができます。つまり、変更に迅速に対応し、より早くお客様に更新された情報を提供できるということです。また、翻訳版のドキュメントのサポートにも役立ちます。コンテンツの単一ソース化により、英語から日本語への翻訳を迅速に行うことが可能になり、別の言語の追加も簡単にできます。

この手法は私たちのワークフローで非常に役立っているため、ご参考までにご紹介したいと思います。

DRY 原則に従うため、私たちは静的サイトジェネレータの Jekyll に組み込まれている機能を利用しました。Jekyll には、データファイルと呼ばれるコンテンツを単一ソース化するメソッドがあり、これにより DRY キーと呼ばれるキーと値のペアを含むファイルを作成することができます。

DRY キーの作成は簡単です。リポジトリに _data フォルダを作成し、DRY キーを格納するための YML ファイルを作成するだけです。作成する YML ファイルは、英語の DRY キー用ファイル (en.yml) と日本語の DRY キー用ファイル (ja.yml) です。各 YML ファイルでは、「キー : 値」のペアで DRY キーが構成されています。以下はその一例です。

my-dry-key: “Insert text for DRY key.”

注 : いずれの YML ファイルでもキー名は同じですが、値はターゲット言語に訳されています。

苦労したのは、どのテキストを DRY キーにするかということでした。考えた末、ドキュメントサイト全体に表示される警告ボックスの見出しを DRY キーとして作成しました。これらは頻繁に参照されるためです。

alert-leader-tip: "TIP" 
alert-leader-note: "NOTE"
alert-leader-important: CAUTION
alert-leader-warning: "WARNING" 

また、ドキュメントサイトで参照される最も一般的な手順用の DRY キーも作成しました。これらは、みなさんも見覚えがあるのではないでしょうか。

step-login: "Log in to the Fastly web interface."
step-login-configure: "Log in to the Fastly web interface and click the **Configure** link."
step-login-account: "Log in to the Fastly web interface and click the **Account** link from the [user menu](/en/guides/about-the-web-interface-controls#about-the-user-menu. Your account information appears."
step-select-service: "From the **All services** page, select the appropriate service. You can use the search box to search by ID, name, or domain."
step-click-edit: "Click the **Edit configuration** button and then select the option to clone the active version. The Domains page appears."
step-click-origins-tab: "Click the **Origins** link. The Origins page appears."
step-click-settings-tab: "Click the **Settings** link. The Settings page appears."
step-click-content-tab: "Click the **Content** link. The Content page appears."
step-activate-deploy: "Click the **Activate** button to deploy your configuration changes."

これは実際にはどのように表示されるのでしょうか。次のように Liquid タグで参照するだけで、DRY キーをドキュメントで使用できます : {% t my-dry-key %}

私たちのカスタム Jekyll プラグインは、各 DRY タグを読み取り、DRY キーの値を出力します。例えば、「Uploading custom VCL 」ガイドの次のセクションを見てみましょう。

このガイドは以下のように処理されています。

1.  {% t step-login %}
2.  {% t step-select-service %}
3.  {% t step-click-edit %}
4.  Click the **Custom VCL** tab. The Custom VCL page appears.
5.  Click the **Upload a new VCL file** button. The Upload a new VCL file page appears.

t は、コードが (裏で巧みに処理されて) ページの言語を使用して、DRY テキストの適切な翻訳版を取得することを示しています。ほとんどの翻訳サービスでは単語ごとに課金されるため、翻訳には高いコストがかかります。日本語の DRY キーを使用することで、フレーズを一度だけ翻訳して複数の場所で使用できるため、翻訳コストの削減につながります。

DRY キーを最初に導入した際は、ドキュメントの適切な場所に DRY キーを挿入するために何度も検索と置換を繰り返す必要がありました。しかし今では、Fastly インターフェースで何かが変更された場合、一か所を変更するだけでドキュメントサイト全体に変更を反映させることができるため、時間も節約できます。これにより、更新された情報をより早くお客様に提供することができ、ミスや更新する必要があるガイドを見逃す可能性を減らすことができます。

さらにこのシステムでは、ドキュメントに新しい翻訳版を追加する際にスケールアップすることが可能です。既存の DRY キーファイルをコピーして名前を変更し、それらのキー値を翻訳するだけで済みます。

実際にはもう少し手を加える必要があり、それを解説するには Fastly 独自の翻訳システムの説明が必要になるので、その話はまた別のブログ記事でお話ししたいと思います。