As developers, many of us believe that our primary responsibility is to understand the requirements and hastily write code to meet them. However, this is a flawed notion. Among the many responsibilities of a developer, writing proper documentation is also crucial. Unfortunately, this is often misunderstood or poorly executed. Some developers write so extensively that the core requirements or business logic get lost—a case of "using a cannon to kill a mosquito."

Simply writing line-by-line documentation doesn't automatically make your code readable. Documentation should focus only on what is essential, especially when it explains critical project requirements or business logic. This doesn't mean you should neglect documentation entirely for straightforward cases; instead, well-written, self-explanatory code often eliminates the need for excessive documentation.

Striking the Right Balance in Documentation and Code

A common scenario involves working with database tables to check if data exists or to count the number of rows for further processing. For repetitive tasks like this, a helper function is an excellent solution. Consider the following example:

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();
    }
}

// Usage
$productTotalCount = $this->BaseModel->getTotalCount('products', ['brand_id' => $brand_id]);
if ($productTotalCount > 0) {
    // Further processing...
}

This approach is clear and concise, with no unnecessary complexity. The function serves its purpose effectively, and its usage is intuitive. However, let’s look at a contrasting example:

class My_Model extends Models
{
    /**
     * Get Simple Read Of Method
     * to get a specific row of a table
     */
    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();
    }
}

// Usage
$productTotalCount = $this->My_Model->simple_read('products', ['brand_id' => $brand_id]);
if ($productTotalCount > 0) {
    // Further processing...
}

Here, the simple_read function is being misused for a task it wasn’t designed for. If the products table has 20 rows, the function will return only the first row of the table. If no data is present, it returns NULL. This creates a problem: is NULL comparable to 0? Absolutely not. Consequently, the code will throw an error if the table has no data. Writing detailed documentation for such flawed code won’t make it better. It’s akin to adding layers of explanation to a fundamentally broken solution.

Lessons Learned:

1. Prioritize Clarity in Code: Strive to write clear and self-explanatory code. If your code is easy to understand, it reduces the need for extensive documentation.
2. Avoid Misuse of Functions: Understand the purpose of each function and use it appropriately. Avoid bending a function's behavior to fit a task it wasn’t designed for.
3. Focus on the Essentials: Documentation should highlight what truly matters, such as critical business logic or non-obvious functionality.
4. Think Before You Code: As the saying goes, "Think before you act." Similarly, write code after careful thought and planning. Don’t defend flawed practices under the guise of meeting deadlines.

By balancing meaningful documentation and 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.