ファーストクラスのライブラリを出荷しています。知っておく必要がある落とし穴はありますか?


12

私は自分のキャリアで「ファーストクラスライブラリ公開」の成果を解き明かそうとしているWeb開発者です。コミュニティの経験を活用して、可能な限りスムーズに進むための提案や推奨事項があるかどうかを確認したいと思います。知っておく必要のある詳細や落とし穴はありますか?ビルドプロセスについて何か特別なことはありますか?

私がいる場所は次のとおりです。

  • ライブラリはユニットテストされており、約97%のコードカバレッジがあります。
  • APIは十分に文書化されており、インテリセンスサポートのxmlドキュメントが作成されています
  • パブリック/プライベートクラスアクセサーが正確かつ正しいことを確認しました。すべてのゲッター/セッターについても同じことが言えます
  • エラー処理は私が望んでいるほど優雅ではありませんが、私は締め切りに間に合っており、今のところ「それがうまくいく」ことを受け入れています
  • わかりやすいログはありません。Debug.Writelineが広く使用されていました...最近、これが私の経験不足を反映していることがわかりました:(

あなたのアドバイスは大歓迎です!

ライブラリはレポートの生成に使用されます。標準の帽子-読み取り専用データベースに接続し、計算を実行し、データをフォーマットし、応答ストリームに出力します。


私は、辞めたプログラマーの一人を補うためのフリンジリソースとしてタップされ、このタスクは「歯を切る」プロジェクトとして私に与えられました。クラスライブラリは、プロダクションコードを記述するときに使用する社内の他のプログラマ向けにリリースされる予定です。


2
詳細が必要な場合、どのようにリリースしますか?売り出し中?共有のためにオープンソースをリリースしますか?契約している契約ごとにクライアントにリリースしますか?フルタイムの雇用主のプロジェクトの一環として、開発組織の残りの部分にリリースしますか?フルタイムの雇用主のクライアントの可用性に新製品のv1.0としてリリースしますか?
ジミー・ホッファ

@JimmyHoffa:質問への回答を追加しました。お時間をいただきありがとうございます!
JavaScript氏

1
あなたがライブラリーのユーザーであるかのように、それがどのように機能するかを知らない。それを使って何かを構築します。経験に基づいて物事を変更/削除/追加します。次に、それを実際のユーザーにリリースし、フィードバックを取得します。
mike30

おそらく、Sandcastleやその他のドキュメント生成ライブラリを使用して、オフラインの(参考資料)参照資料を作成しますか?
ジェシーC.スライサー

7
リラックス。私の経験では、1つの単体テストと1行のAPIドキュメントさえあれば、このリリースは「社内の他のプログラマーが使用するためにリリースされた」コードの〜95%を超えています。
Carson63000

回答:


8

APIをロックインする

APIを効果的に構築する技術は、構造に関することと同じくらい期待を管理することです。

APIと言うとき、パブリック/内部クラス/メソッドの名前とアクセスレベル(プライベート/パブリック/内部)を具体的に参照しています。

コードがプライムタイムの準備が整っていないのではないかと心配している場合は、最初は常にベータ版として公開できます。

リリース:

  • ベータ版(1.0より前)

    • 複数のAPI破壊変更が含まれる場合があります
    • バージョン間の後方互換性の変更がない可能性があります
    • ポーランド語の欠如があるかもしれません
  • 公式(1.0+)

    • APIは次のメジャーリリースまでロックされています
    • 導入された変更により、後方互換性が保証されます。
  • マイナー(例1.1)

    • バグ修正や機能の実装を含む
    • 追加することはできますが、定義済みのAPIを削除することはできません

APIをバトル強化する必要があると思われる場合は、しばらくベータ版としてリリースしてください。これは、使用可能であることを示していますが、本番および/またはミッションクリティカルなコードには使用しないでください。

多くの人々は番号付きバージョン管理スキームをホグウォッシュのように扱いますが、効果的に使用されると、構造を整理するまで小刻みにスペースを提供することができます。

それがどのように使用されるかについてのあなたの仮定は間違っています

どれだけうまく設計されていても、人々は悪用または代替使用を作成する方法を見つけます。

これを処理する1つの方法は、アクセサー(つまり、プライベート/パブリック/内部)を使用して可能な限り実装をロックダウンすることですが、設計やエンジニアリングの量はユーザーにコードをリリースするほどの洞察を与えません。

コードがどれだけ「完璧」になりうるかは問題ではなく、ユーザーはコードがそうでないことを証明します。

これが、完全な書き換えを行うよりも既存のコードベースを使用する方が常に優れている主な理由であると主張します。せいぜい完全な書き直しで肥大化を抑えることができますが、新しいコードベースには元のコードベースと同じ数の(場合によってはそれ以上の)バグが含まれる可能性が高くなります。

あなたの場合、あなたは最初から戦いを固めているので、あなたも始めることができます。


基地の残りがカバーされているように思えます。APIドキュメントは不可欠であり、テストは将来変更が行われたときに安定性を確保するのに役立ちます。

ログをグローバルに有効化/無効化/フィルタリングする方法が必要になるため、一貫性のあるロギングスキームを実装することは、本番用にコードがリリースされる前に重要になります。ところで、ほとんどの場合、ロギングは実際にはライブラリのインポートと、Debug.WriteLine()からLogging.Debug()、Logging.Info()、Logging.Error()などの出力呼び出しの変更のみを必要とします。ロガー自体は、構成、フィルタリング、および幅広い出力スキーム(exファイル、コンソールなど)の標準実装を提供するだけです。

それ以外は、コードを公開して使用することを検討します。少数のユーザーのみが開始する場合でも。


1
+1 Re:ロギング-TraceSourceを強くお勧めします。コア.NETライブラリの一部であり、ユーザーがコードとapp.configファイルの両方でリスナーをアタッチし、トレースを構成できるため、外部の依存関係を導入しません。
ダンライオンズ

4

これらは、ソフトウェアをリリースするための鍵となる2つのことです。

  • リリースした内容を正確に把握する
  • 期待を管理する

あなたは戻ってあなたがリリースしたものをバグ修正できるようにしたい、そしてあなたのコードが解決する問題を人々に理解してもらいたい。

あなたがリリースしたものを知る

正しくバージョン管理され、署名されていることを確認してください(適切な場合)。ソース管理を使用して、正式にリリースされたバージョンに関連付けられているコードにタグを付けます。これにより、リリースしたソースコードに正確に戻ることができるため、バグの特定が容易になります。また、いくつかの異なるリリースされたバージョンがあるかもしれないときにラインを下るのを助けます。

最新バージョンを簡単に入手して更新できるようにしてください。それがインストーラーであるか、単に共通の共有に置くかは、誰が、いつ、どのくらいの頻度で出荷するかに依存します。

ドキュメントを含む最終リリースを誰かがレビューするようにしてください。ソフトウェアのリリースに神経質になったり興奮したりして、何かを見逃すのはとても簡単です。

期待の管理

制限を文書化し、開発者に合理的に明らかにします。あなたがそれらを見つけたのは良いことです。ソフトウェアの制限を知っていれば、特にあなたがそれらを修正する計画を持っているなら、人々はしばしばより理解しています。

良いか悪いかを問わず、フィードバックを希望する方法を文書化します。内部プロジェクトであるため、全員が共通のバグ追跡システムにアクセスできる場合は、適切なプロジェクトに対してバグを報告するよう依頼してください。

将来的には、可能な場合はAPIの変更を避けてください。これは、顧客を困らせる可能性があるものの1つです。C#では例外はメソッドドキュメントの一部ではありませんが、例外もAPIの一部であることに注意してください。あり後日スローされる例外を向上させることができることがありますが、エンドユーザーに話をし、それがありますどのような影響を参照する必要があります。


0

役に立つ展開のチェックリストがあります。私はデスクトップ開発をしていますが、これのいくつかは翻訳すべきです。以下がその一部です。

全般:

  • NULLであってはならない関数パラメーターのNULLチェックを入れます。これは私が早期に失敗するのを助けます。
  • 不要なコメントとコメントアウトされたファイルを削除します。これらは将来の作業を引き起こします。
  • 「// TODO」コメントを検索します。時々私は自分のためにメモを残します。時々忘れてしまいます。
  • 可能であれば、運用データベースを使用してコードのテストを実行します。これにより、すべてのデータベースの変更が運用サーバーで適切に行われます。
  • 大量のログを記録します。特に初期展開の場合。実際、私のコードは通常この時点でゲル化されるため、最後にロギングを保存します。クラッシュした状況になりたくないので、「この時点でXの値が何であるかを知っていれば」と言います。事前に計画してみてください。
  • Facadesでサードパーティのライブラリ呼び出しをラップしてみてください。これにより、将来のライブラリの変更が簡単になり、ライブラリに必要なもののチェックリストが提供されます。

.Net固有:

  • 使い捨てオブジェクトでDispose()を呼び出していることを確認してください。コード分​​析またはFxCopを使用して、このようなケースを見つけます。
  • すべてのイベントハンドラーを適切にアンフックしていることを確認してください。これにより、メモリリークが防止されます。
弊社のサイトを使用することにより、あなたは弊社のクッキーポリシーおよびプライバシーポリシーを読み、理解したものとみなされます。
Licensed under cc by-sa 3.0 with attribution required.