The Importance of Writing Meaningful Code and Documentation

Many developers believe that the first priority is to understand the requirements and write code quickly. However, this view is flawed. One of the responsibilities of a developer is to write appropriate documentation, but this is often misunderstood or poorly implemented. Some developers write so verbosely that the core requirements or business logic are obscured - this is like killing a chicken with a bull's-eye.

Writing documentation line by line does not automatically make the code easier to read. Documentation should focus only on necessary information, especially when explaining key project requirements or business logic. But this doesn't mean that documentation can be completely ignored for simple cases; on the contrary, well-written, self-explanatory code can often reduce the need for excessive documentation.

The balance between code and documentation

A common scenario is to use a database table to check if data exists or count the number of rows for further processing. Helper functions are an excellent solution for such repetitive tasks. Consider the following example:

<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>

This approach is clear and concise without unnecessary complexity. The function accomplishes its purpose efficiently and is intuitive to use. But let’s look at a comparative example:

<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>

Here, the simple_read function is being misused for a task for which it was not designed. If the products table has 20 rows, this function will only return the first row of the table. If there is no data, it returns NULL. This raises a question: can NULL be compared to 0? Absolutely not. So if there is no data in the table, the code will throw an error. Writing detailed documentation for this flawed code doesn't make it any better. It's like adding layers of explanation to a fundamentally wrong solution.

Lessons learned:

1. Prioritize code clarity: Strive to write clear and understandable code. If your code is easy to understand, it reduces the need for extensive documentation.
2. Avoid function misuse: Understand the purpose of each function and use it correctly. Avoid changing the behavior of a function to suit a task for which it was not designed.
3. Focus on key points: Documentation should highlight what is really important, such as critical business logic or non-obvious features.
4. Think before you act: As the saying goes, “think before you act.” Likewise, write code after careful thought and planning. Don’t use meeting deadlines as an excuse to maintain flawed practices.

By balancing meaningful documentation with well-structured code, developers can ensure their work is efficient and easy to maintain. Ultimately, it's not just about writing code; it's about writing good code.

The above is the detailed content of The Importance of Writing Meaningful Code and Documentation. For more information, please follow other related articles on the PHP Chinese website!