At a minimum, I've always tried to comment when something took extra research/effort for me to understand and implement, and definitely if I learned something c

At a minimum, I've always tried to comment when something took extra research/effort for me to understand and implement, and definitely if I learned something critical along the way. I'll try and point that out in the comment. In addition, if I had to do something in a non-obvious, or non-clean way, or if it would appear so to someone else, I comment that as well and try to explain why it didn't/wouldn't work in seemingly more obvious approaches to the problem. Also, this is the enterprise side of me, If I had to lean on a specific subject matter expert to understand a narrow piece of the domain before I could work through an issue, I try to be very specific about who that person was, but also what their specific domain expertise was - people leave, reorgs happen, but the goal is to have the reader understand where to go, provided that knowledge was transferred, independent of names and departments. Example: I did a lot of data engineering in insurance earlier in my career, and sometimes it's really important for someone to understand non-obvious special conditions in code ("Generally, Product X had this provision, but we sold a policy form from 1998-2002 that had a slightly different provision, so you have to average the calc over a 3 month window instead of a specific effective date") - that's a generalized example of where I had to go pull hard copies of contracts to find that out, and I'd spare any future developer a week of research.