A client came to us with their WooCommerce shop last week. The request sounded simple: add a tiered discount for VIP customers. But when my developer opened the functions.php file, he found a monster. One 1000-line function with no comments and no documentation at all. The original developer was long gone, and nobody knew what this thing did, only that it had something to do with shipping calculations. Total nightmare.
This is a classic case of technical documentation debt. It’s the developer version of writer’s block: instead of a blank page, you’re staring at a tangled mess of code with no context. And it costs clients real money.
Your code’s “why” matters more than its “how”
My first thought was to reverse-engineer it. I told my dev, “Let’s trace the logic and figure it out.” That was a mistake. We burned three hours mapping the function calls and still weren’t sure what the variables were even for. We were stuck. We couldn’t add the new feature without risking the whole shipping calculator. For all we knew, some odd edge case for international shipping would break the moment we touched it.
The problem wasn’t the complexity of the code. It was the missing story behind it. Why was it built this way? What problem was it solving? The previous developer never wrote any of that down. I picked this up from a post on carlalexander.ca about getting past writer’s block, and the principle carries over: you have to know what you’re trying to say. With code, that means documenting your intent.
/**\n * Calculates custom shipping rates based on user role and cart weight.\n *\n * Business Logic: VIP members get a 50% discount on shipping for orders\n * under 10kg. This was a special request from marketing to boost the\n * loyalty program enrollment in Q4 2022.\n *\n * @param float $shipping_cost The original shipping cost.\n * @param int $cart_weight_kg The total weight of the cart in kilograms.\n * @return float The adjusted shipping cost.\n */\nfunction calculate_custom_vip_shipping( $shipping_cost, $cart_weight_kg ) {\n if ( ! is_user_logged_in() || $cart_weight_kg >= 10 ) {\n return $shipping_cost; // Exit early if not applicable.\n }\n\n $user = wp_get_current_user();\n if ( in_array( 'vip_customer', (array) $user->roles ) ) {\n // Here's the kicker: apply the 50% discount.\n $shipping_cost *= 0.5;\n }\n\n return $shipping_cost;\n}So, what’s the point?
Writing good technical documentation isn’t about being a novelist. It’s about saving the next person, and often your future self, from hours of frustration. Before you write a single line of a new feature, you should be able to answer a few questions:
- What problem is this solving?
- Are there any weird business rules I need to account for?
- How does this function fit into the bigger picture?
Answering them in a comment block or a README file takes maybe 15 minutes. That’s it. Those 15 minutes can save thousands of dollars and weeks of delays later.
This stuff gets complicated fast. If you’re tired of debugging someone else’s mess and you just want your site to work, drop my team a line. We’ve probably seen it before.
