ドキュメントがあなたの親友である理由

Written by

in

(更新後も機能し続けるソリューションを作成する方法)

「アプリはパブリック API のみを使用でき、現在出荷されている OS 上で実行する必要があります。」 Apple アプリレビューガイドライン

新しいフレームワークを使い始めて、「もうすべて自分で理解できるだろう、ドキュメントを読むのは長すぎる」と思ったことがあるのは、決して一人ではありません。私たちの多くは、最初に試してから指示を見るという自然な調査本能を持っています。それはまったく普通のことです。

ただし、この段階では、調子に乗って、コードはうまく機能するものの、システムの明白ではない機能に依存しているという状況に陥りがちです。

単に「自分で解決する」だけでは不十分な場合があるのはなぜですか?

フレームワーク、特にクローズドなフレームワークは、複雑で多層のシステムです。多くの場合、次のような内部ロジックと最適化が隠蔽されます。

* 公開ドキュメントには記載されていません。
* 動作が将来も維持されることを保証するものではありません。
* 新しいバージョンのリリースにより変更される可能性があります。
* 開発者に知られている、まだ修正されていない機能が含まれている可能性があります。

私たちが直感的に行動すると、文書化されたルールではなく、ランダムな観察に基づいてアーキテクチャを構築してしまうリスクがあります。これにより、コードが更新に対してより敏感になる可能性があります。

ドキュメントは制限ではなく、信頼できるサポートです

フレームワーク開発者は私たちを助けるマニュアルを作成します。ドキュメント内で動作すると、次の結果が得られます。

* 安定性;
* サポート;
* 予測可能なシステム動作。

これらの制限を超えると、さらなるリスクを負うことになり、そのようなコードの保守がより困難になります。

実験?確かに。ただし、境界を理解した上で。
好奇心は開発者にとって素晴らしい特性です。新しいことを探索して試すことは絶対に必要です。しかし、ここに小さな願いがあります。

最も快適に実験できる方法は、ベスト プラクティスに頼ることです。

ドキュメントは、どのパスが最も安全で作成者によってサポートされているかを示すマップです。

外部の視点: 専門家のアドバイス

私たちは経験豊富な同僚から次のことを学ぶことがよくあります。

* 役立つ講座を開催しているので、
* カンファレンスで講演する
* 素晴らしい本やブログを書き、
* 独自のビジョンを共有します。

彼らの多くは本当に貴重な経験を共有しています。しかし、覚えておく価値があるのは、著者のアプローチが公式ドキュメントと矛盾している場合、それらは脆弱であることが判明する可能性があるということです。

このような「経験的パターン」は、次のような場合があります。

* フレームワークの特定のバージョンでのみ動作します。
* アップデートに敏感です。
* 異常な状況では予期しない動作をする可能性があります。

コミュニティから学ぶことは素晴らしく、やりがいのあることです。ただし、アドバイスは、たとえ最も権威のあるものであっても、必ず公式マニュアルで注意深く確認する必要があります。

SOLID について少し説明

SOLID 原則からの 3 つのアイデアは、このアプローチを完全に補完します。

* オープン/クローズの原則: パブリック API を通じて動作を拡張するように努め、可能であれば、隠れた実装に依存しないようにします。
* リスコフ置換原則: 特定の実装ではなく、契約に依存します。そうしないと、内部での変更が予期せぬ問題を引き起こす可能性があります。
* 依存関係の反転: 詳細ではなく抽象化に基づいて依存関係を構築します。

実際には、これは、フレームワークの内部の文書化されていない詳細に結び付けられると、システムが脆弱になることを意味します。
パブリック インターフェイスとコントラクトに基づいて、次の結果が得られます。

* フレームワークの変更からコードをより適切に分離します。
* テストの容易さ。
* アーキテクチャの予測可能性と信頼性。

バグがある場合はどうすればよいですか?

すべてがルールに従って行われたにもかかわらず、結果が期待を満たさないことも起こります。フレームワークは進化しますが、常に完璧であるとは限りません。そのような場合:

* 問題を再現する最小限のサンプルを構築します。
* 文書化された API のみが使用されていることを確認してください。
* バグレポートを送信してください – 開発チームはあなたの仕事に感謝し、支援しようと努めます。

例が回避策に依存している場合、開発者がサポートを提供することは非常に困難になります。

フレームワークを最大限に活用する方法

*ドキュメントを参照してください。
* 著者のガイドと推奨事項に従ってください。
* 説明されている機能内で実験してください。
* インターネットからのアドバイスを公式情報源で確認してください。
* フレームワーク契約を尊重しながらバグをローカライズします。

結論

フレームワークは、独自のゲームルールを持つ強力なツールです。それらを忘れると、コードが過度に脆弱になる危険があります。しかし、私たちは皆、作成された製品が長期間存続し、マイナーアップデートのたびに緊急の修正を必要としないことを望んでいます。

マニュアルとドキュメントは、真に信頼できるソリューションを作成するのに役立つ優れたサポートです。

ソース

https://developer.apple.com/app-store/review/guidelines/
https://en.wikipedia.org/wiki/SOLID
https://en.wikipedia.org/wiki/API
https://en.wikipedia.org/wiki/RTFM

Comments

Leave a Reply

Your email address will not be published. Required fields are marked *

DemensDeum
Privacy Overview

This website uses cookies so that we can provide you with the best user experience possible. Cookie information is stored in your browser and performs functions such as recognising you when you return to our website and helping our team to understand which sections of the website you find most interesting and useful.