何年も前、専門家と開発の第一人者の確立した意見は私には明らかでした。通常、次のように表現されます。「コードにコメントが必要な場合、これは悪いコードです。書き直し/リファクタリング/単純化/削減する必要があります。」 つまり コメントや説明を必要としないフォームに持ってきてください。 一般に、このアプローチは非常に普遍的であり、多くの場合に機能します。 私の友人のWeb開発者の多くは、チームで働いていても、自分のコードにコメントすることはなく、これを非常に普通のことだと考えています。 Rubyのシンプルさ、つまりコードを部外者にも理解できるシンプルさについての神話は、おそらく語っています。 しかし、私の個人的な経験とWebアプリケーション開発チームのいくつかのエピソードから、開発者が通常注ぐよりもコードのコメントとドキュメントにより多くの注意と時間を注ぐ状況と理由があると確信しました。
インターネット上には、コードを書く技術、特定のプログラミング言語の規則と推奨事項についてのあらゆる観点を示す記事や投稿が多分あることをすぐに警告します。 もちろん、私はそれらのすべてを知ることはできませんので、問題の歴史への遠足はありません。 私の個人的な経験についての私の個人的な話だけがあります。
私の短編小説の主な論文は次のとおりです。「コードの複雑さを判断できるのは著者だけです。」
そのため、まず、ルールが正確に機能するタイミングを明確にする必要があります。「コメントの代わりに、コメントが冗長になるようにコードを変更してください。」 いくつかの場合にのみ機能します：
- コードが無条件に記述されている場合：長すぎる（おそらく開発者は標準ライブラリをよく知らず、多くの余分なコードを自分で書いた）か、複雑すぎる（perlスタイル、5行以上の関数の長さを持つ関数の単一行チェーン）
- コードに、特定のPLメソッドおよびテクニックに対してめったに使用されない、または特性が含まれていない場合
それだけです！ これらの場合、このコードをやり直すことは本当に良いです。 やり直し、コードが短くなり、明確になり、同僚にとって理解しやすくなることを確認し、最後にコメントを書いてください！ そして、私はすでに自分のアイデアを説明する場所に着きました。
アイデア1の説明：「コードの複雑さを適切に判断できるのは著者だけです。」
たとえば、5人で構成されるプログラマのチームを想像してください。 マネージャーと2人のデザイナーが一緒に働いています。 プログラマのチームは、1人のプロと4人の普通のレベルのプログラマで構成されています。 誰もコードにコメントしていません。 おそらく、プロジェクトの展開方法について誰かが書いた簡単な指示があるでしょう。 チームはドキュメントを保持しません。 顧客は意思決定と優先順位を変更し、開発プロセスでのドキュメントの準備に費やした時間を実際に支払うことを望みません。 多くの中間レベルのWeb開発スタジオは、ほぼこの方法で機能します。
1人または2人のプログラマがチームを離れ、別のプロジェクト、別のスタジオ、または休暇中にどうなるでしょうか。 おそらく、彼らの代わりに、コードを与えられ、タスクと...を与えられた他の1人と2人の開発者が連れて行かれます。 以前は、HRマネージャーは「他の人のコードを理解し」、「チームで作業する」ことができるかどうかを尋ね、もちろん、できると答えます。 そして、新しい到着者はコードと同僚と一対一になり、「なぜここにいるのか...」または「そこにあるのはなぜか」という質問に喜んで答えることができますが、これは仕事の邪魔になります。 したがって、開発者は「プロジェクトを中断する」ことを余儀なくされます。 他の誰かのコードを脳で「実行」するために費やす作業時間は、それを通り抜けて何をしているのかを理解するために恐ろしいことです。 例で説明します。
次のような関数を想像してください：
def update
list = current_user.lists.update（params [：id]、params [：list]）
終わり
コードのシンプルさのルールという点では、それはただの楽園です。 ここでコメントすることは何もありません。1行で、まったく問題はありません。 ただし、paramsはページ上の単純なフォームではなく、Backbone.jsのJavascriptコードを使用して形成され、リストはリストではなく、前のコマンドで残った名前とモデルがテストでThingsと呼ばれるようになったと想像してくださいこのモデルのbefore_saveで関数がハングアップし、いくつかのフィールドを取得し、これらのフィールドのデータに応じていくつかのURL（おそらくHTTPプロトコルのエラー制御なし）を解析する保留中のタスクを作成し、後で受信した回答が別のテーブルに保存されるようにします また、例外を発生させ、それらに関するメッセージをどこかで...エラー収集サイトに送信することもあります。エラー収集サイトでは、プログラマが思い出すとすぐにアクセスが許可されます。 完全に異なるコントローラー（たとえば、API）は、これらのフィールドの値をBackboneビューにajaxします。 ちなみに、リストの元のコンテンツであるThingsとはまったく異なり、RABLパーサーを最初に渡してJSONを作成することで、この関数がテンプレートをレンダリングする必要があることを明確にすることもできます。 完全なセットについては、たとえばcronにアクセスせずに、いくつかの制限があるホスティングで機能することを明確にします。 また、DBMSの品質により、NoSQLが使用されます。
上記の例はフィクションではなく、特別な合併症ではありません。 実際のプロジェクトでは、アプリケーションの一部の機能を実現するためのステップも増えます。 ただし、コードが複雑であるかどうかは、常にコードの作成者自身が知ることができます。 問題は、このアプリケーションに新しい機能を実装する必要がある人は、必然的に、使用可能なコードベースのほぼ全体をインタープリターではなく自分の脳で「実行」する必要があることです。 彼は、コードを書き始める前にこれを行うので、マネージャーが何らかの形でレポートで正当化する必要があります。または、コードを書くプロセスでこれを行います。これは最悪のオプションです。 なんで？ そして、そのような仕事の結果は非常に低品質であり、休暇から戻った著者はとにかくすべてをやり直すからです。 そして、あなたは彼がプロジェクトを理解したという事実のために新参者に支払いますが、結局それはまだ何の利益ももたらさなかった。
別の一般的な問題があります。
プロジェクトNでは、Mの機能は通常XYZを使用して実装されます。 コードを完全に知らない場合、または構造を説明しXZYが使用するプロジェクトドキュメントを読んでいない場合、開発者はX、YまたはZがすでに使用されているかどうかを知ることができません。 もしそうでなければ、なぜ使わないのか。 なじみのないプロジェクトですぐに作業を開始して新しいものを作成できるプログラマーはいません。これは「クールな開発者」に関する神話です。 同様の状況がもたらす最良のことは、開発者ができる限り自分のタスクを実行し、コードレビューにそれを与え、「なぜこのようにしたのか、[技術のリスト]を使用するのが一般的だから」というコメントでコードを取得することです次のように可能であったため、なぜこれを行ったのですか：[存在を自分で判断することが不可能なエンティティーの説明（例えば、実動サーバー上のデータベース内のトリガーまたは関数の存在]）
それで、私が提案することは、読者に長い間尋ねる時です。 まず、作業中のコードでいくつかの簡単なことを行います。
- このコードの仕組みを説明してください。 簡潔ではありますが、クラスを含む各ファイルの先頭に、クラスが実装するものを記述してください。 クラスメソッドの前に、メソッドが受け取るものと、作業の最後に作成するものを簡単に説明し、データが通過するチェーンを簡単に説明します。 また、モジュールファイル内。 移行によって作成されたフィールドの自動計算値と割り当てについてコメントします。 関数呼び出しの長いチェーン（3つ以上）の場合、シーケンスだけである場合、何が何を引き起こすかのチェーンを記述します。
- 少なくともクラスまたはモジュールの宣言の直後に、同じ場所の各ファイルにTODOブロックを入力します。
- 各ファイルにIN_WORKブロック（好きな名前）を入力します。このファイルには、現在どの場所がリワーク/リファクタリング/古くなっているかを記述し、代わりにXYZクラスのBLABLAを使用します。
- すべての事実を必ず記述してください。その存在は入手可能なドキュメントから推測することはできません！
最後の段落で例を挙げます。たとえば、プロジェクトがMySQLと互換性がなく、開発者がこのDBMSにプロジェクトを展開しようとして半日費やした場合、「MySQLをサポートしていません！」と言わないでください。 これに対して、「どうしてこれを知らなかったの？」という声がよく聞こえます。 そして、この男に「なぜ聞かなかったの？」というフレーズを言うと、あなたは確信できます。 あなたのプロジェクトにはすでにドキュメントに関する大きな問題があり、これはすでにあなたに損害を与えている。 結局のところ、私たちの誰もが彼が知らないすべての正確なリストを知りません！
ご清聴ありがとうございました。コードは常に明確で、シンプルで、文書化してください。