⌛ I want to share an incident from a previous job: a Salesforce record couldn’t be saved because of a trigger issue interacting with a flow in a non-obvious way. The responsible developer was in a different time zone and unreachable. None of the solution architects and consultants could decipher the trigger logic, primarily because there were no comments in the code.
It took a while for me to be asked for help (after business hours), and then more time to get the right access before I could troubleshoot. This experience really drove home the importance of well-commented code.
There’s a misconception, influenced by Uncle Bob’s "Clean Code", that “comments lie” or “code should be self-explanatory.” The reality is that solution architects and project managers are often non-coders, yet they might need to understand logic to resolve issues. Especially when developers are unavailable or in different time zones. Well-placed comments can reduce downtime and headache.
🤔 Why comments matter:
👉 Clarity: Comments help non-developers (and sometimes even developers!) quickly grasp what’s going on.
👉 Maintenance: Code evolves. Comments can give a history of changes and the reasons behind them.
👉 Onboarding: Junior developers and new hires learn faster with context provided in comments.
👉 Future-proofing: Code you wrote months or years ago can become unfamiliar - even to you! Comments serve as reminders and guides.
👉 Collaboration: In global teams, it’s common for devs to be on the other side of the world. Well-documented logic can prevent delays.
🙏 Be nice to your worthy and brave solution architects and project managers who are willing to read code!
🙏 Be nice to your future self!
🙏 Be nice to your future ex-co-workers or junior devs!
🙏 Think that the future person who will be looking at your code might not be having a nice day but you can do your best to make it less difficult.
Yes, it's true that comments can become outdated or misleading. But that’s an argument for maintaining them - not dismissing them! It doesn't cost much to get in the habit and follow a disciplined approach: update comments alongside code changes.
Code itself shows what the program is doing, but good comments explain WHY certain choices were made. This context can be important for someone seeing the code for the first time or debugging an unexpected edge case under a short deadline. They also can give the history: over time there are patches, optimizations, or hotfixes. Comments can describe or give hints of how the logic evolved and trade-offs - that can prevent someone from unintentionally reversing a crucial change.
As John F. Woods once joked in the comp.lang.c++ newsgroup in 1991:
“Always code as if the guy who ends up maintaining your code will be a violent psychopath who knows where you live.”
😅
