I'm using "What", "Why" and "How" here as defined in the article. Problem with documenting in the code itself: The "Why" is further from the code than the "Wha

I'm using "What", "Why" and "How" here as defined in the article. Problem with documenting in the code itself: The "Why" is further from the code than the "What", and the "How" is further away still. Explaining "What" a function does is close to the code, I just put some comment lines before the function/type, etc. and maybe some into the definition. They are just to make the code better readable for the human. But where do I put the "Why"? I could put it with the "What", but often the "Why" depends on somewhere completely different in my code (or someone elses code). eg. "Why am I using a map here instead of a list? Because the remote API expexts a JSON object and the map is easier to Marshal into that". But what if the remote API changes? Okay, I change the code that deals with it, and update the comments for that code. Do I also change the comments everywhere else where this map is used? For that matter, is it explained anywhere else in the code why that is a map instead of a list? The "What" says "this code iterates through the maps values and appends an underscore to each", but is the "Why", which explains why that is a map there as well? In every function that works on that map? My point is, not only is it difficult to explain everything in the code, it's also very very difficult to keep this documentation up to date, because the relationship between a comments location, and the code it belongs to, becomes more complicated the further up we go from the "What".