The comments will tell you what was intended at some point regardless of what is happening. In any mature code base that includes these "what not why" comments, the comments will inevitably document old intents that have since changed.

> Maybe I'm biased because I'm pretty proficient in the business domains I specialize in, so I can understand, conceptually, what the application is suppose to support and consider the validity of the programmer's intent as well as the code's function.

Given that, why do you need these kinds of comments at all? 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?

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.

Unless you write the comment, then the code, then change the code and don't update the comment. Now if the code is wrong, both the comment and code are wrong.

In current languages letting code handle the 'what', and comments handle the 'why' works well enough. Not saying it is a perfect system, but the idea of the comment being expanded to include the 'what' as well doesn't seem like progress in the right direction to me.

If you're working with a relatively simple application where the information the application deals with is conceptually simple: you're absolutely right, explaining what and then having code that has a finite set of possible intents would just be wordy. On the other hand, I gave an example of ERP system inventory costing algorithms in another answer in this general thread where the complexity is different: cost can mean different things under different circumstances and different processes. We try to generalize these algorithms into lower lever functions, but you have to understand the what to know how it's appropriate to use the function... or if it is actually achieving it's goal: it may be coded in a way to be valid in all but the use cases targeted. There simply is no one size fits all answer to how to appropriately comment code (or if to do it at all).

As for bad comments and comment rot... any code, commented or not, can be written poorly or not maintained properly. Yes it's an extra moving part, and if you're not going to be as diligent about documentation as the code then, yes, often times your better without it. I think, however, it's better to force the issue. I don't think you need freestanding documents but by god if you have comments and I see code in a code review where the comments have been neglected: reject that submission.