適切な方法で頭の痛い問題や文書契約を回避する

契約は、ソフトウェア開発の不欠な组成部分です。それらは開発コストを削減し、開発者の日常を楽にします。しかし、問題があります。古いおとぎ話のように、適切に文書化されず、口コミでチーム全部に伝えられないため、物事が複雑になることがよくあります。広がりながら、合意は変化します。总是、新しい詳細が表现され、古い詳細は失われます。最終的には、すべてのチーム メンバーが頭の中にそれぞれの容易のイメージを持っています。

さらに悪いことに、チームがこれらの合意事項の文書化を開始するとき、彼らはでたらめにそれを行い、多くの場合、疎結合のドキュメントの极其混乱を制作します。その半分は近期最新でさえありません。

この記事では、契約書を文書化する正しい方法を説明しますので、契約書が役に立ちます。

では、どうすれば協定を役立つものにできるでしょうか。それらを文書化するだけでなく、次のようにします。

• それらは使いやすいです。
• これらの合意に従うのに必要性な労力は最长限でした。
• これらの契約がまだ有効であるかどうかを正确理解するのは簡単です。
• なぜこれらの協定が具备するのかを谅解するのは簡単です。
• 抱负的には、それらは自動化されていました。

  
  

契約を分類する技术はたくさんあります。それらを抽象、化レベルで划分します。

• コードレベルの合意;
• アーキテクチャレベルの合意;
• プロセスレベルの合意。

さまざまなレベルの合意には、それらを文書化し、さまざまなメリットをもたらすさまざまな策略が这个必要です。レベルごとに見ていきましょう。

コードレベルの規則

これらの協定の的は、コードを統一し、具有的で、読みやすいものにすることです。ここではいくつかの例を示します。

• 一重的使用符の代わりに二重的使用符を的使用します。

• これらの呼び出しをメソッドにラップするConfigクラスを除いて、コードから ENV を直接呼び出すことはありません。

• Service オブジェクトには接尾辞Serviceと 1 つのパブリック メソッドcallあります。

  
  

この種の契約は、読者の認知負荷を軽減し、未找到のコードに早く慣れるのに役立つように弄成されています。マーティンが言ったように、コードは書かれたものよりも最大化 10 倍多く読み取られます。

Ruby on Rails フレームワークに関するあなたの意見とは裏腹に、Ruby on Rails フレームワークにはconvention over configuration根底にあり、これにより、Rails 開発者は誰でも他の人のプロジェクトを開いてすぐにナビゲートすることができます。

では、これらの規則を文書化するにはどうすればよいでしょうか。リンターツール！適切なリンター ルールがない場合は、一人のリントを記述します。ほとんどすべてのリンターでそれが可能性です: これはの例で、ここはの例です。

このような規則にリンターを操作すると、次の 3 つの利点が得られます。

• 開発者がそれらについて考える有必要的はありません。リンターはすべてのエラーを強調透露し、多くの場合、それらを修修爱します。
• チームでコード レビューを施用すると、レビュアーはこれらのことについて考える有必要がなくなり、より关键なことを検討する時間が増えます。
• 開発者は、開発サイクルの原来の段階で問題に気付くので、後でコンテキストに戻る時間を費やさずにすぐに计算します。契約を維持する方が安くなります。

  
  

もう 1 つのボーナス: 新しいリンター ルールを制成することは、ジュニア開発者にとって優れたトレーニングです。このタスクを结束了している間、彼はコードの解答と AST の構築について多くを学び、言語をより深く解读するでしょう。

アーキテクチャ レベルの規則

これは、アーキテクチャを思慮深く、一貫性があり、統一することを目标とした高レベルの合意です。いくつかの例:

• Python を运行して一般而言のサービスを記述し、システムの負荷の高い有些に Elixir を記述します。
• バックエンドは記述された结构でエラーを返します。

• プロメテウスでメトリックを送信するには、各サービスが必要です。 /metricsエンドポイントでは、メトリックを送信するためのポートがPROMETHEUS_PORT環境変数によって構成されます。

  
  

このような合意は、認知負荷を軽減するだけでなく、さらに 3 つの問題を解決します。

1. 運用コストを削減します。サービスが同じ步骤で、同じログ样式で、同じメトリクスを公開する場合、サービスの維持とインシデントへの対処がはるかに簡単になります。
2. 設計コストを削減します。開発者は毎回ゼロからアーキテクチャを設計する不这个必要はありません。事前事后に考えていたので、首要的なことを気にすることなく、相应の機能またはサービスのみを設計する不这个必要があります。
3. 通信系统費を削減します。 Kafka でのサーバーの応答またはイベントの组织形式が前期に決定されている場合、開発者は対話のたびに議論する有必要的はなく、単に規則を图案填充するだけで済みます。

   
   

このような契約はより複雑であり、私は 2 つのステップで修复することを好みます。

ステップ 1 - 説明

Architecture Decision Record (ADR) は、このような合意を文書化するためのツールです。その活力は、契約とともにメタ情報をキャプチャすることです。なぜそのような契約が採用されたのか。どの代换案が議論されましたか。最後に改訂されたとき。契約はまだ有効ですか？

これにより、新しいチーム メンバーは決定の原因を的理解し、周りの人にそれについて尋ねる有必要がなくなります。

ADR はいくつかの注意なブロックで構成されています。

1. 協定はどのような問題を解決しますか?
2. 問題を解決するためにどのようなオプションが検討され、その長所と短所は何でしたか?
3. 最終的に選ばれた選択肢は？

   
   

実装コストの計算など、追加のブロックが具有する場合があります。

ADR は、変更履歴や議論の履歴を確認できるシステムに贮存しておくと快速です。私が選んだのは Github と Notion で、それぞれに長所と短所があります。 Github の利点は、すぐに使用的できるレビュー ツールとバージョン履歴があることです。データベースとタグを进行操作する快速さから、Notion は優れたソリューションになる可能会性があります。また、非開発者でも簡単に処理できます。

ADR を使い始めたい場合は、を基准することをお勧めします。ここには、さまざまな ADR テンプレートとその选用方法步骤の例があります。

ステップ 2 - 自動化

ADR は、コード レベルの規則よりも自動化が難しく、設計リンターはまだ発明されていません (残念です!)。ただし、契約の種類によっては、有些的に自動化することも可能性です。

言語、ライブラリ、およびインフラストラクチャへのサービスの埋め込みに関する契約のサービス テンプレートを制作および刷新します。その後、開発者は新しいサービスをゼロから制作するのではなく、テンプレートからコピーして、構成済みの Dockerfile やメトリクスの発行などをすぐに受け取ります。

同様に、1 つのアプリケーション内でクラス ジェネレータを制成できます。いくつかのアプリケーション層 (コントローラー => フォーム => サービス オブジェクト) について合意したとします。その場合、新しい機能のすべてのレイヤーを一名に转化成する単純なコンソール コマンドを制成できます。

この最简单的方法では自動化できないいくつかの原則に允许している場合は、トラッカーのマージ リクエストまたはタスクに自動的に追加されるチェックリストを整体できます。したがって、開発者はタスクを渡す前にそれらをすばやく確認できます。

プロセスレベルの合意

各企業には、プロセスに関する多くの合意があります。たとえば、次のとおりです。

• 会社での採用の仕組みについて説明します。
• リリース ロールアウト プロセスの説明。
• 大規模なタスクの設計レビューの要件。
• 週に 2 回チーム ミーティングを実施し、現在のタスクと障害について話し合います。

  
  

较近まで、私はこれらの契約を文書化することについて考えていませんでしたが、それらは会社の成功失败に大きく影響します。これらの合意の文書化は、上記のタイプの利点をもたらすだけでなく、プロセスを有效率化し、それらを目に見える空间图形に移し、それらの比较便宜について考えることができます.

からアイデアを得ました。彼は、ADR に似たツールである Process Decision Record (PDR) を提案しました。唯一の違いは、アーキテクチャの決定ではなく、プロセスに関する決定を記述していることです。さらに、彼は、各 PDR に「再考日」を入れることを提案しました。これは、採用後nか月後に、ドキュメントに戻って問題が最善の方法で解決されるかどうかを確認する日付です (ちなみに、同じことができます)。 ADRあり）。

自動化に関しては、できることはほとんどありません。 Jira でワークフローを設定したり、会議のリマインダーを設定したり、その週の結果のプレゼンテーションを自動的に準備するボットを作为したりすることで、部のプロセスを自動化できます (ただし、これは美国の会社で行いました)。

しかし、多くの場合、プロセスを実際に自動化することはできません。主な目標は、従わないよりも簡単に従えるようにすることです。それでも、プロセスが従うのがすでに簡単な場合でも、契約書を文書化することは还として役立ちます。的形式化と合适化により、プロセスを解决できます。

それで、結果はどうですか？

ドキュメンテーションとその後の自動化は好处です。開発に費やす時間が短縮され、アプリケーションがよりサポートされやすくなり、プロセスがよりスマートになります。

「私たちは善人であり、それがなくてもコードを開発できる」ため、これはすべて并非要な官僚主義であると考えることができます。しかし、実際には、協定はかなりの時間とお金を節約し、従業員の神経細胞を保護します。確かに、契約に反するものを絶対的に扱って拒否する一定要はありません。これは、契約を升级更新する一定要があるか、一开始にその側面のいくつかについて考えていなかったことを示している将会性があります。

チーム内で契約書の文書化をまだ開始していない場合は、抽像化レベルの低いものから高いものへと移行してください。コード レベルの契約書から始めて、アーキテクチャ レベルの契約書から始めて、プロセス レベルの契約書に対処してください。契約文書はチームで開発する習慣であり、抽像度の低い什么概念から始める方がはるかに簡単です。

また、すべてのタイプが記事に記載されているわけではありません。たとえば、設計合意書をライブラリ コンポーネントとして文書化できます。

新しいタイプの契約はそれぞれ、同じ 3 つの段階を経ます。

1. それを文書化する方式方法を考えてください。
2. それを自動化する的方法を考えてみましょう。
3. 時間が経つにつれて、それを維持するよりも多くのリソースを節約するようにしてください。

   
   

そして最後。文書化プロセス中に、既存の契約の几部が明らかに、何の合理合法化もされておらず、チームの時間を浪費し、一般来说的に威害であることが判明する場合がありますが、あなたはすでにそれらに慣れています。この場合、チームの心にある習慣の壁を应对し、合意を受け入れるよりも拒否する方が为重要な場合があることをチームに納得させる必要的があります。しかし、それはまったく別の話です。