将来の開発者のために働く

通常、成功するソフトウェア製品は、その寿命にわたって多くの開発者の手に渡ります。 あなたはあなたのプロジェクトの保護者のチェーンのリンクの1つにすぎず、あなたが書いたコードの各行は、将来の開発者によっていつか研究されるあなたが残したアーティファクトです。 あなたがあなたの前に来た開発者の決定を引き継いだように、他の開発者はあなたが今日下した決定を引き継ぎます。 彼らは私たちからのすべての誤解、私たちによる角を切る、私たちによって適用された誤解されたパターンと技術、細部への不注意、私たちの怠iness、私たちの変化、ホイップアップされた変更、キャビネットのスケルトン、汚れた洗濯物を受け継いでいます。 そしてはるかに少ない-私たちの規律の利点、私たちの議論と準備。







プロジェクトの開発者として、あなたは将来の開発者のニーズを予測し、世話をするのに可能な限り最高の立場にいます。 私たちのプロジェクトで私たちが下す良い決定はすべて、その生産性に波及効果をもたらします。 なぜこれが重要なのですか？ Bob MartinがClean Codeで尋ねているように、「悪いコードで問題が発生したことはありますか？ では、なぜそれを書いているのですか？」 将来プロジェクトに取り組むチームの世代の条件を改善するのと同じ戦略が、現在のチームに役立ちます。 6か月前に立ち往生したコードの暗い隅に戻ると、Future Developerが初めて目にするときに知るよりも、もう少し詳しく知っています。 あなたが他の開発者に任せるヒントと光沢から、あなた自身が将来利益を得るでしょう。 状態が悪く、チームの枯渇につながる貢献が難しいプロジェクト。 作成している製品の品質と将来のサポートの容易さに投資することは、未来と現在のための幸せで生産的な職場への投資です。



Future Developerを直接成功に導くために使用できるいくつかのプラクティス（特定の順序なし）を作成したいと思います。

1.全体的なリファクタリング

プロジェクトが古くなり、要件が複雑になるにつれて、この複雑さを制御するために新しいパターンと手法を適用するよう努めています。 パターンまたはアプローチが割り当てられたタスクに対処するかどうかをすぐに言うことはできません。 ほとんどの場合、別の開発者がコードのこの部分を変更しなければならないときに、その重要性の確認または反論が現れます。 これらのパターンは、問題を解決するために受け入れられる合意に成長する場合があります。



これには大きな利点があります。それは私たちの意図を説明しています。 同様の方法でコードの問題を解決しようとすると、将来の開発者はコードの断片がどのように連携するかを予測し始め、それによって診断と変更に必要な時間を短縮できます。



多くの場合、私たちが予約しているのは、合意に至らなかったり、古いゴミのようなコードで無視されたりしていないパターンのミッシュマッシュです。 これはさまざまな理由で発生します。受け入れられた契約がプロジェクトの他の領域に適用されるほどうまく機能しないか、新しい開発者が目標を達成するための適切な契約またはパターンの存在を知らなかった可能性があります。



Ruby on Railsの内部には、多くの強力なビューと規則が確立されています。 これにより、開発者はプロジェクトに接続し、すぐに生産性を高めることができます（ただし、以前にこのフレームワークを使用した経験があれば）。 時々、私たちはこれらの合意を無視し、それによってそれらの強さを弱めます。 たとえば、鉄道プロジェクトでは、いくつかの異なるスタイルで構築されたコントローラーに定期的に気付くことができます。 resource_controller



ようなものを使用して作成されるものもあれば、Railsで採用されている標準のresource_controller



規則に従うものもあれば、ランダムアクションからの単なるゴミダンプです。 別の一般的なアンチパターンはプロジェクト全体に散らばり、可能な場合はどこでも構成データを初期化します。



システムを構成するために半ダースの異なる方法をサポートする必要はなく、プロジェクト内でどの原則を構築する必要があるかによって、システムを明確かつ理解可能にする必要はありません。 1つのアプローチを試して受け入れた後、時間をかけて古いコードに戻り、新しい方法でリファクタリングします。 これは、arbitrary意的な制限を課す必要があるという意味ではありません。 たとえば、構成の一部をプロジェクト内に保持し、環境変数に一部を配置して展開を支援することは理にかなっていますが、同時に、構成データを使用するための1つの共通の構造とアクセスパターンが必要です。



READMEまたはドキュメントリポジトリに契約を追加します。 最初に、これにより、将来の開発者がシステムに新しい機能を追加しやすくなり、コンポーネントの構築方法を理解できるようになります。

2.デッドコードを根絶する

しばらくの間すでに存在していたシステムのもう1つの一般的な機能は、デッドコードの形の苔の層です。 これらはプロジェクトのコンポーネントであり、以前はビジネスにとって重要でしたが、時代遅れであり、長い間誰も必要としませんでした。 ほとんどの場合、プロジェクトでは、機能のそのような部分をチェックするフルスタック受け入れテストを多数見つけることができますが、これらのテストは残りの通過を遅くするだけです。



この機能が二度と需要にならないことを常に確信できるとは限らないため、そのようなコードを削除したがらないことがあります。 経営者に尋ねると、「いつか離れて、いつか便利になります」という質問に答えます。 これは間違ったジレンマです-将来的には指のスナップだけで再び使用できる可能性があるため、ゆっくりと腐敗するコードを維持する必要があります。 このコードが無関係であるためにこのコードをバイパスした場合、指をクリックするだけで、大きな労力をかけずに機能するようになる可能性は低くなります。 あなたは古いコードがあなたを一番下に引っ張って、それをサポートするのに時間を費やすことを心配しています、それはいつかそれが必要になるというわずかな可能性があるからです。 たぶん。 気づきませんが、それに多くの時間を費やし、そのようなコードを削除する代わりに、リポジトリでゆっくりと腐敗させます。



しかし、このコードの存在は、将来の開発者にとって潜在的なトラップになることをさらに犠牲にします。 これは、実際に生きているシステムのコンポーネントから注意をそらし、システムのある側面を理解またはデバッグしようとすると、誤ったトレースにつながる可能性があります。 緊急事態では、すべてが落ちたとき、デッドコードは貴重な時間を費やすためにしばらく待つノイズです。 リポジトリで関連性のある活発で実際に機能するコードのみをサポートすることにより、プロジェクトをサポートするための全体的なコストを削減し、将来の開発者がシステム全体をより速く理解できるようにします。



長い間放棄されてきたコードを削除します。 最終的には、後で戻る必要がある場合に備えて、バージョン管理下にあります。 「後で彼に戻る」必要性にだまされてはいけません。 このコードになんらかの意味がある場合、なぜ使用されなくなったのですか？

3.情報を送信する

実際、私たちのプロジェクトに加えて、コードを書くために使用するツールのいくつかにも成果物があります。 たとえば、git commitで良いメッセージの衛生状態を構成するものについては、多くの受け入れられた慣行がありますが、プロジェクトはまだそのようなコミットストーリーを収集しています。

 jp@oeuf:~/workspace/blog(master*)$ git log --oneline app/controllers/application_controller.rb 8ec7f99 fuck i dunno lol ffa919a shut up, atom parser a33e9fa fixing again cecc9dc one more time 968a28f fixing 3e3aeb2 ws 1fc597e pagination edea155 adding dumb feature
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

将来の開発者が必然的にgit blameを使用してこの機能のコンテキストを理解するようになる場合は、ファイルで実際に何が起こっているのかを理解するのに役立つ詳細を彼に残してください。 --squash



、 commit --amend



、 rebase



およびその他のツールを使用して、ブランチを統合する前にコミットを使用可能な状態にします。 完了したらコミットを書き直します。適切であると思われるすべてのものを含めて、完了した作業を要約してください。 正しい文法とつづり。 他の人が読んで理解する必要があるものを公開しています。 Future Developerにサービスを提供し、必要な詳細を含むわかりやすい記録を確保してください。

 jp@oeuf:~/workspace/blog(master*)$ git log app/controllers/application_controller.rb commit 8ec7f998fb74a80886ece47f0a51bd03b0460c7a Author: John Pignata <john@pignata.com> Date: Sat Nov 3 14:11:12 2012 -0400 Add Google Analytics helper commit 968a28f366e959081307e65253118a65301466f2 Author: John Pignata <john@pignata.com> Date: Sat Nov 3 13:49:50 2012 -0400 Correct ATOM feed validation issues Using the W3C Validator (http://validator.w3.org/appc/), a few trivial errors were reported: * <author> should have a <name> node within it and not text * Timestamps should be in ISO8601 format This change fixes these issues and improves the spec coverage for the XML document. commit 3e3aeb27ea99ecd612c436814c5a2b0dab69c2c3 Author: John Pignata <john@pignata.com> Date: Sat Nov 3 13:46:24 2012 -0400 Fixing whitespace We're no longer indenting methods after `private` or `protected` directives as a matter of style. This commit fixes whitespace in all remaining classes. commit 1fc597e788442e8cc774c6d11e7ac5e77b6c6e14 Author: John Pignata <john@pignata.com> Date: Sat Nov 3 12:34:50 2012 -0400 Implement Kaminari pagination Move from will_paginate to kaminari in all controllers. The motivation is to be able to paginate simple Array collections without the monkey patching that will_paginate uses. * Consolidate helpers * Clean up whitespace commit edea15560595bab044143149a7d6e528e8ae65d2 Author: John Pignata <john@pignata.com> Date: Sat Nov 3 12:27:16 2012 -0400 Add ATOM feed for RSS readers * Include Nokogiri in Gemfile for its builder * Add AtomFieldBuilder model * Add link to feed from index page
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

4.インターフェースに光沢を向ける

一部のルビーは、オブジェクト内の視覚的なメソッドを避けています。 目的は何ですか？ とにかく、実際にはsendを介してメソッドが呼び出されます。 なぜそれらのいくつかをシャックルしますか？ メソッドを他のヒープに追加するだけで、将来の開発者がそれを使用したい場合は可能です！ 私たちはみんな大人ですよね？



システム内の各オブジェクトが単なるメソッドのダンプである場合、個々のオブジェクトがどのように使用され、どのメッセージが意図されているかを理解することは、あなたを含めて誰にとっても難しくなります。 オブジェクトのパブリックインターフェイスの設計では、システム内の他のオブジェクトがオブジェクトとどのようにやり取りできるかを明確にする必要があります。 システム内の各オブジェクトの役割とそれらの間の相互作用が明らかでない場合、各オブジェクトを個別に理解するだけでなく、システム全体を理解するのにかかる時間が長くなります。



インターフェースを小さく、集中させるために、できるだけ多くのコンポーネント内部を非表示にします。 プロパティのパブリックインターフェイスが明確で一貫性があり、名前が適切であることを確認するために、さらに努力してください。 これにより、将来の開発者は、各オブジェクトの使用方法について理解しやすい信号を受け取り、各オブジェクトを再利用する方法を強調します。 これらの前提を伝え、パブリックインターフェイスの明確な境界を尊重するために、メソッドの可視性を明示的に述べます。

5.コメントを残します。ほとんどはRDocです。

開発者としてのコード内のコメントに対する私たちの感情は、矛盾していると最も正確に説明できます。 一方で、コメントは読者が特定のコードがどのように機能するかを理解するのに非常に役立ちます。 一方で、それらの正確性を保証するものは何もありません;コードに関するコメントは、翼で待っている嘘です。 開発者に尋ねると、彼らはドキュメントを高く評価して読んでいると答えますが、ほとんどのプロジェクトには実際には小さな、ほとんど失われた関連性のREADMEファイルと近くのウィキ墓があります。 さらに、オープンソースライブラリを使用する場合、詳細なRDocドキュメント、新鮮なREADMEファイル、優れたコード例が必要になることがよくあります。 くそー開発者：ドキュメントをサポートしていません。おそらく誰かが彼のためにそれをすることを期待しています。



Single Responsibility Principleのようなことに注意を払い、オブジェクト間の弱い接続のパターンを使用するほど、プログラムの期間中に結合された多くの小さなオブジェクトで構成されるシステムが見え始めます。 これにより、システムはより柔軟になり、オブジェクトを何度も使いやすくなりますが、妥協点があります。大規模システム内のオブジェクトの場所を理解するのが難しくなり、より多くの労力と時間が必要になります。 通常のリファクタリング手法をすべて適用して、面倒な行間コメントを削除し、オブジェクトをできる限り読みやすくすることができますが、システム内でオブジェクトがどのように相互作用するかは、Future Developerを混乱させる可能性があります。



RDocスタイルのドキュメントは、多くのオープンソースプロジェクトにあります。 Googleを使用してupdate_attribute



がコールバックを呼び出すかどうか、およびselect_tag



シグネチャを理解すると、通常、Ruby On RailsのRDocページが表示されます。 プロジェクトの同様のドキュメントを作成すると、将来の開発者は、システムの広大なコンテキストでオブジェクトの役割を決定しようとするときに、より理解することができます。 クラスおよび/またはメソッドの上部に短い宣言文があることは、コードの読者にとって重要なことです。 しかし、これらのコメントの関連性をサポートする確立された文化がなければ、コードリーダーの見当識を損なうマイナスの効果もあります。 ドキュメンテーションの欠如よりも悪いことは、ドキュメンテーションの質が悪いことだけだということを忘れないでください。

6.意図を明らかにするテストを作成します。

プロジェクトにドキュメントを提供する1つの方法は、テストを使用することです。 テストでは、コンポーネントの動作を記述するだけでなく、そのようなドキュメントが次のように高品質であることも確認します。 彼女は処刑されています。 コメントとは異なり、テストにうそをつくことはできません。 それらは緑かそうでないかのどちらかです。 RSpecやminitest / specなどのツールは、このサイドドキュメントの生成に役立ち、テストケースブロック内の散文を奨励します。 残念ながら、赤緑緑のリファクタリングサイクル中に動作するコードを取得しようとして、過去の英語の単語を見ることもあります。 英語の記述を無視した結果、テストではオブジェクトの動作が考えられているほど表示されないことがあります。



テストがまったくないプロジェクトを見つけるのと同じくらい苦痛です。テストがシステムの動作を理解するのに役立たないプロジェクトを見つけるのです。 テストもサポートを必要とするコードであるため、将来の読者にその目的を非常に明確に説明する必要があります。

 it "works" do data = File.open("fixtures/projects.txt").read index = ProjectIndex.new(data) index.should have(40).projects last_project = projects.last last_project.title.should eq("ORCA") last_project.customer.should eq("Romney-Ryan 2012") last_project.deploy_date.should eq(Date.parse("2012-11-06")) end
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

さて、ここで何が機能しますか？ この説明は一言では意味がなく、この例では複数のチェックが一度に実行されますが、まったく意味がありません。



仕様のスタイルでテストを作成する場合、英語の説明はあなたと一緒に行く必要があります。 これを実現する1つの方法は、ドキュメント形式でRSpecを実行することです。

 jp@oeuf:~/workspace/project-manager(master)$ be rspec --format documentation spec ProjectIndex .new instantiates an index given the contents of a project CSV file #projects returns a collection of projects from the index Project #title returns the project title #customer returns the Customer record for the project #deploy_date calculates the deploy date from the latest project status
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

緑色のドットの森の代わりに、ドキュメント形式はネストされた説明、コンテキスト、および指定した例の見出しを提供します。 これにより、テストがオブジェクトの実際の動作をどの程度完全に明らかにするかをすばやく評価できます。 この形式の出力に焦点を当てることにより、テストスイートの通信価値を大幅に向上させることができます。 赤緑緑のリファクタリングサイクルのリファクタリングステップを使用して、テストを、オブジェクトの存在理由、動作、およびこのように実行する理由の明確な説明に変えます。

将来の開発者は喜んで

これらは、他の誰かが請求書を支払うという合理的な仮定の下で、変更に向けてプロジェクトを準備する方法のほんの一部です。 作業中の現在のプロジェクトの構築と運用を担当する次の目について考えてください。 サポートの難しさやリリースしたものの質の低さから、私たち全員が後悔を感じています。 したがって、コードに残したすべてのかわいい熊手に対して温かい気持ちを抱くことをやめ、代わりに、将来の開発者が到着のために地面をどれだけ準備したかによってあなたに支払うべき酒の量をゆっくり計算し始めます。



「未来の開発者」という言葉を借りた（読んだ：盗んだ）Dave Yeuに感謝します。



考え、質問、コメントはありますか？ それらを共有してください！ Twitterでは@jpignataというニックネームで見つけることができます。また、john @ pignata.comで電子メールを受け取ることもできます。 読んでくれてありがとう！



これは翻訳であり、上記の座標は元の記事の著者を指していることを思い出させてください。 PMでコメントやコメントをお寄せいただければ幸いです。 ありがとう