意味のあるコードとドキュメントを書くことの重要性

多くの開発者は、要件を理解し、コードを迅速に記述することが最優先事項であると信じています。しかし、この見方には欠陥があります。開発者の責任の 1 つは適切なドキュメントを作成することですが、これは誤解されたり、実装が不十分であることがよくあります。開発者の中には、核となる要件やビジネス ロジックがわかりにくくなるほど冗長に書く人もいます。これは、目玉で鶏を殺すようなものです。

ドキュメントを 1 行ずつ書いても、自動的にコードが読みやすくなるわけではありません。ドキュメントは、特に主要なプロジェクト要件やビジネス ロジックを説明する場合、必要な情報のみに焦点を当てるべきです。しかし、これは、単純な場合にはドキュメントを完全に無視できるという意味ではなく、逆に、よく書かれた一目瞭然のコードにより、過剰なドキュメントの必要性を減らすことができます。

コードとドキュメントのバランス

一般的なシナリオは、データベース テーブルを使用してデータが存在するかどうかを確認したり、さらなる処理のために行数をカウントしたりすることです。ヘルパー関数は、このような反復的なタスクに対する優れたソリューションです。次の例を考えてみましょう:

<code>class BaseModel extends Models
{
    function getTotalCount($table_name, $condition = []) {
        $query = "SELECT COUNT(*) AS total_rows FROM " . $table_name;
        if (!empty($condition)) {
            $query .= " WHERE " . $condition;
        }
        return $this->db->query($query)->get();
    }
}

// 使用示例
$productTotalCount = $this->BaseModel->getTotalCount('products', ['brand_id' => $brand_id]);
if ($productTotalCount > 0) {
    // 进一步处理...
}</code>

このアプローチは明確かつ簡潔であり、不必要な複雑さはありません。この機能はその目的を効率的に達成し、直感的に使用できます。しかし、比較例を見てみましょう:

<code>class My_Model extends Models
{
    /**
     * 获取表格特定行的简易读取方法
     * 用于获取表格的特定行
     */
    function simple_read($table_name, $condition, $column_name = "*") {
        if ($table_name == '' || $condition == '') {
            return false;
        }
        return $this->db->select($column_name, false)->where($condition)->get_where($table_name)->row();
    }
}

// 使用示例
$productTotalCount = $this->My_Model->simple_read('products', ['brand_id' => $brand_id]);
if ($productTotalCount > 0) {
    // 进一步处理...
}</code>

ここでは、simple_read 関数が、意図されていないタスクに悪用されています。 products テーブルに 20 行がある場合、この関数はテーブルの最初の行のみを返します。データがない場合は NULL を返します。ここで疑問が生じます: NULL は 0 と比較できますか?絶対に違います。したがって、テーブルにデータがない場合、コードはエラーをスローします。この欠陥のあるコードについて詳細なドキュメントを書いても、それ以上改善されるわけではありません。それは、根本的に間違った解決策に何層もの説明を追加するようなものです。

学んだ教訓:

1. コードの明瞭さを優先する: 明確でわかりやすいコードを書くように努めてください。コードが理解しやすい場合は、広範なドキュメントの必要性が減ります。
2. 関数の誤用を避ける: 各関数の目的を理解し、正しく使用してください。関数が設計されていないタスクに合わせて関数の動作を変更することは避けてください。
3. 重要なポイントに焦点を当てる: ドキュメントでは、重要なビジネス ロジックや明白ではない機能など、本当に重要なものを強調する必要があります。
4. 行動する前に考えてください: ことわざにあるように、「行動する前に考えてください」。同様に、慎重に考え、計画を立ててからコードを作成してください。期限を守ることを言い訳にして、欠陥のある慣行を維持しないでください。

意味のあるドキュメントと適切に構造化されたコードのバランスを取ることで、開発者は作業が効率的で保守が容易になることを保証できます。最終的には、単にコードを書くだけではなく、優れたコードを書くことが重要です。

以上が意味のあるコードとドキュメントを書くことの重要性の詳細内容です。詳細については、PHP 中国語 Web サイトの他の関連記事を参照してください。