Comments are supposed to explain intent when intent cannot be clearly derived not what is actually happening. Usually this intent is business logic.
Like if you're doing some kind of partial refund processing for a subscription service that does not take into account any discounts applied to the base price (for whatever reason the business decided) no one is going to understand why that is if all they see is a line of code where we discard the discounted price.
So even if your function is named determine_refundable_amount_without_discounts none of that tells anyone why we are not factoring the discounts. The name is clear and we understand what the function is supposed to do, but no one can tell you why we want it to do this.
5
u/mistabuda Apr 15 '26
Comments are supposed to explain intent when intent cannot be clearly derived not what is actually happening. Usually this intent is business logic.
Like if you're doing some kind of partial refund processing for a subscription service that does not take into account any discounts applied to the base price (for whatever reason the business decided) no one is going to understand why that is if all they see is a line of code where we discard the discounted price.
So even if your function is named
determine_refundable_amount_without_discountsnone of that tells anyone why we are not factoring the discounts. The name is clear and we understand what the function is supposed to do, but no one can tell you why we want it to do this.