> Given that, why do you need these kinds of comments at all?
Because in large, logically complex systems, especially large complex systems that are sold to many customers like my area of expertise, ERP systems implementation & development, there are many, many right answers (there are many wrong answers, too). Take inventory costing; my current project is adding an industry specific inventory handling methodology to an existing ERP system. Consider the inventory unit costing: there are multiple methods (standard, weighted average, FIFO, retail method, etc.), there can be different derivations and components (purchase cost, landed costs, material costs, direct overhead cost, indirect overhead costs) and to top things off, not only do systems implement more than one of these at a time, sometimes different of these can be useful concurrently depending on context: if I'm analyzing my vendor costs per item, I might not want my overhead costs in the picture, but I still need overheads in the capitalized cost of the item when determining Cost of Goods Sold when I ship product out, for example. In software, if I see a function like (not real, way oversimplified pseudo-code):
I might not know exactly where or how to use this properly, even having some expertise. Was the developer trying to get at a landed cost? Are they expecting that this would only be used in the invoice matching process and shouldn't really be used outside of that? I might get that contextually from surrounding code or from the (various) contexts that the function is called in, but now I have a research project trying to figure out why they created this so that I don't use it in inappropriate contexts... or I can re-invent the wheel (not a good strategy). My professional knowledge will tell me where to look for other telltale signs to figure out the answer, but not immediately just from looking at the code since there are multiple valid answers. If I had:
// Function for determining item costs for three way matching.
// We record freight costs separately from item material costs,
// but invoices have no such breakout, so we do the math here
// to facilitate the matching process.
now I get it. It's not that the system has a simplified view of landed costing, but there is a specific purpose that was trying to be accomplished by this function.
> You already know what the code is supposed to do anyway, why introduce a comment that you might later forget to update, leaving less knowledgeable colleagues confused?
Most of the time the comments in the code I work with really don't change much in regard to intent. If the comments get too close to describing the logic, then yes, the comments don't age well as the logic that achieves that intent is improved, but those are the comments that are probably not needed. The contextual comments, however, are important (even for me to understand what I wrote after some time has passed).
Even so, I was speculating/rationalizing on why people might hold that somehow "ignorance is bliss" when I spoke of junior staff. I don't hold that belief myself. I haven't found that withholding information even from junior/support staff is better than giving more complete pictures. I find the informed person much more useful that the person guessing at what it could all possibly mean and fit together.
Because in large, logically complex systems, especially large complex systems that are sold to many customers like my area of expertise, ERP systems implementation & development, there are many, many right answers (there are many wrong answers, too). Take inventory costing; my current project is adding an industry specific inventory handling methodology to an existing ERP system. Consider the inventory unit costing: there are multiple methods (standard, weighted average, FIFO, retail method, etc.), there can be different derivations and components (purchase cost, landed costs, material costs, direct overhead cost, indirect overhead costs) and to top things off, not only do systems implement more than one of these at a time, sometimes different of these can be useful concurrently depending on context: if I'm analyzing my vendor costs per item, I might not want my overhead costs in the picture, but I still need overheads in the capitalized cost of the item when determining Cost of Goods Sold when I ship product out, for example. In software, if I see a function like (not real, way oversimplified pseudo-code):
function calc_item_trans_cost() { total_item_trans_cost = item_cost + item_freight_cost return total_item_trans_cost }
I might not know exactly where or how to use this properly, even having some expertise. Was the developer trying to get at a landed cost? Are they expecting that this would only be used in the invoice matching process and shouldn't really be used outside of that? I might get that contextually from surrounding code or from the (various) contexts that the function is called in, but now I have a research project trying to figure out why they created this so that I don't use it in inappropriate contexts... or I can re-invent the wheel (not a good strategy). My professional knowledge will tell me where to look for other telltale signs to figure out the answer, but not immediately just from looking at the code since there are multiple valid answers. If I had:
// Function for determining item costs for three way matching. // We record freight costs separately from item material costs, // but invoices have no such breakout, so we do the math here // to facilitate the matching process.
function calc_item_purch_cost() { total_item_purch_cost = item_cost + item_freight_cost return total_item_purch_cost }
now I get it. It's not that the system has a simplified view of landed costing, but there is a specific purpose that was trying to be accomplished by this function.
> You already know what the code is supposed to do anyway, why introduce a comment that you might later forget to update, leaving less knowledgeable colleagues confused?
Most of the time the comments in the code I work with really don't change much in regard to intent. If the comments get too close to describing the logic, then yes, the comments don't age well as the logic that achieves that intent is improved, but those are the comments that are probably not needed. The contextual comments, however, are important (even for me to understand what I wrote after some time has passed).
Even so, I was speculating/rationalizing on why people might hold that somehow "ignorance is bliss" when I spoke of junior staff. I don't hold that belief myself. I haven't found that withholding information even from junior/support staff is better than giving more complete pictures. I find the informed person much more useful that the person guessing at what it could all possibly mean and fit together.