Code Commenting Techniques

Inline comments are there to explain the WHY, not the HOW. Regardless of whether they're inside actual code, or in a low-code solution like RPA, comments are there to explain certain scenarios that may not be clear just by reading the source code itself. Their purpose is to make it easier for support/maintenance staff to understand certain decisions the developer made while building the solution, when changes need to be made at a later stage. The HOW part of the whole thing should be readable from code itself, which requires certain practices as well - proper naming of variables, classes, functions, etc. In RPA this means naming flows, subflows, UI elements, variables and sometimes even actions (if possible) in a way that makes it easy to understand. Inline comments come into play when certain practices are applied that are not really easy to understand based on what's visible in the code itself. This might be things like: 📌 Using image recognition / OCR / keystrokes and similar less-preferable approaches when DOM object interactions don't work 📌 Adding static wait times instead of dynamic "wait for {event}" actions when the event cannot be captured 📌 Handling specific nuances of the target application, such as temporary errors that can be ignored or certain windows closing / losing focus 📌 Using scripting in some unconventional way to work around funky issues with the target application 📌 Etc. It is supposed to be considered as part of the solution documentation. The best documentation for code is code itself that is readable and easy to understand. Inline comments add the explanations for unconventional methods that are not readable and easy to understand from the code itself. Like in the screenshot below, where we need to press a button that has already been pressed before in the same subflow, so that we bring back the window that it normally opens to front after it has been pushed to back by another button. It might seem unnecessary, as the window is supposed to be already open. Someone might think this step could be removed if they ever get to do maintenance of this solution. They could think that this slows the flow down and as such it should be deleted to optimize it. But doing so would break the flow. In similar cases, people could question the use of image recognition to press a button, or using keystrokes to populate a text field. It may seem inefficient and unstable, considering that using DOM object selectors is supposed to be more reliable. But for legacy apps that don't allow that or simply have their UIs built in ways that make DOM objects inaccessible to RPA tools, this could potentially lead to wasting time trying to rebuild a working solution in an attempt to make it "better". Inline comments are thus there to compliment the code that should already be readable, with explanations that are not obvious enough. But they should never be used to repeat what's already supposed to be obvious from reading the code itself.

As a QA Architect, I was raised on Uncle Bob's clean coding practices. But AI brings a whole new dimension to writing clean code. Here are some AI clean coding practices I’ve written for my upcoming GitHub Copilot classes. In the spirit of Uncle Bob, we’ll call these Uncle Mike’s AI Clean Code! 🔤 Descriptive naming for promptability — Use clear, meaningful names to help AI understand the function or variable’s intent. 💬 Comment as prompt — Write natural-language comments that act as prompts for AI-assisted code completion. 🧩 Standardize function signatures — Keep function patterns predictable so AI can autocomplete with more accuracy. 🪓 Modular and intent-based design — Break code into small, purpose-driven chunks to guide AI generation better. 📘 AI-readable docstrings — Include concise docstrings that clearly explain the function’s purpose and return value. ✨ Consistent formatting & indentation — Apply standard formatting so AI can easily parse and continue your code style. 🚫 Avoid abbreviations — Spell out names fully to eliminate confusion and improve AI's contextual understanding. 🗂️ Use semantic sectioning — Group related code under labeled comments to help AI follow code structure. 🔢 Avoid magic numbers and strings — Replace unexplained literals with named constants for clarity and reuse. 📥 Prompt-driven variable initialization — Name variables based on their source or purpose to guide AI suggestions. ✅ Write self-descriptive tests — Give test functions names that clearly describe expected behavior and edge cases. 🧹 Avoid code noise — Remove dead code and clutter to prevent misleading AI completions. 🏗️ Prompt-aware file structure — Organize files logically so AI tools can infer intent from directory and file names.

Every developer's nightmare - looking at your own code that's written 2 years ago and having no clue what it does. It's always better to write code like you are explaining it to your future self 𝐃𝐞𝐬𝐜𝐫𝐢𝐩𝐭𝐢𝐯𝐞 𝐧𝐚𝐦𝐢𝐧𝐠 - A name like calculateUserTaxRate() is much better than just calc() because it tells you what the function actually does. 𝐀𝐝𝐝 𝐂𝐨𝐦𝐦𝐞𝐧𝐭𝐬 - Don’t just say what the code is doing. Explain why you wrote it that way. 𝐒𝐢𝐧𝐠𝐥𝐞 𝐫𝐞𝐬𝐩𝐨𝐧𝐬𝐢𝐛𝐢𝐥𝐢𝐭𝐲 - Every function should do one specific thing, and do it well. 𝐂𝐨𝐧𝐬𝐢𝐬𝐭𝐞𝐧𝐭 𝐬𝐭𝐫𝐮𝐜𝐭𝐮𝐫𝐞 -  Write your code in a way that reads like a story, so others can easily follow it. 𝐃𝐨𝐜𝐮𝐦𝐞𝐧𝐭𝐚𝐭𝐢𝐨𝐧 -  Use README files and clear commit messages to explain how things work and why changes were made. 𝐖𝐫𝐢𝐭𝐞 𝐭𝐞𝐬𝐭 𝐜𝐚𝐬𝐞𝐬 - They help others (and your future self) understand exactly how your code is supposed to behave. 𝐑𝐞𝐟𝐚𝐜𝐭𝐨𝐫 - If something looks confusing now, it will be even harder to understand later. Make it better while it’s fresh. Pro tip: Write your code assuming the person fixing it later is having a really bad day and knows where you live. 😂 Remember:  You're not just writing for the computer.  You're writing for the developer who has to work with this code at 2 AM. and who knows that developer might be you in future again 😅 #SoftwareDevelopment #CleanCode #DeveloperLife #Programming Images Credits: Stackovermemes

Another helpful hint (and this one's going to get lots of argument): Let's talk about commenting code. There are 3 schools of thought, and all have been vehemently supported by supervisors of mine in previous jobs: 1. Comment everything because that's your documentation. 2. Comments suck and take up vertical space. Don't use them. 3. Comment only what's needed and make them good comments. The followers of #1 are assuming that well-commented code means you don't have to write any documentation about how your code works. Since only 1 in 1000 (or fewer) programmers know how to comment code properly, that means most production code has NO documentation, which is a shame. The biggest complaint from the #2 supporters is that, besides taking up space (who doesn't have a mouse with a scroll wheel these days?) they're never accurate and they're not maintained by the author. A comment will say "I'm setting Y to 50 here to start" and then later the code is changed and Y is set to 60. The comment is now wrong. #3 fans know how to comment code. I'm in this group and it's a very, very small group. Here's how you comment code: 1. DO add a header to every public function that doesn't just point out what it does, but demonstrates how the function is used, what the input params are, and what the output is expected to be. Someone else can code a call to this function in his code and know how it works without having to read and decipher everything IN the function. Use the /// comment block. 2. DON'T comment code that is blindingly obvious: // Set x to 5. x = 5; Not only is this pointless, but if x eventually changes to 6, we have to remember to change the comment. 3. DO comment any block of code that is NOT obvious or could be interpreted several ways. These comments show your intent, not your method. // I do this because in some cases it gets set to null elsewhere. var thing = GetThingOrNull(); These rules will give you files with minimal, necessary comments that you don't have to maintain and that show the reader what you were thinking when you wrote the code, which is the one thing they can't get all the time from just reading the code itself. #hugheshelpfulhints

Your code should explain what it does. Your docs should explain why it exists. If you're writing comments that describe what the code does, you're fixing the wrong problem. The code should be clear enough that it doesn't need explanation. Good variable names beat comments. A well-named function beats a paragraph explaining what it does. But here's what code can't tell you: Why you chose this approach over the alternatives. The code shows the solution. It doesn't show the three other approaches you tried that didn't work. What tradeoffs you made. "We're using polling instead of webhooks" is visible in the code. "We chose polling because the third-party API has unreliable webhook delivery" isn't. What constraints shaped the decision. The code shows a simple implementation. It doesn't show that you kept it simple because the team is small and complex would slow everyone down. I've seen engineers spend hours trying to understand why code is "wrong" when it was actually right given constraints they didn't know about. The worst documentation I've seen: Comments that repeat the code. The best documentation I've seen: Three sentences explaining why this approach, not that approach. Document decisions, not implementations. The code will change. The reasoning behind it shouldn't disappear. If future-you can't remember why you built it this way, future-someone-else definitely won't figure it out. How do you decide what's worth documenting? #SoftwareEngineering #TechnicalWriting #EngineeringLeadership

What makes in-code #documentation good? 🤷♀️ 🕸 Explain the why, not the what When documenting a complicated block of code, write #why it exists. Merely explaining what the code is doing line-by-line isn't too helpful. Zero in on the raison d’être of a piece of code. Good documentation digs deeper. --- ⚖️ Shoot for the right balance in docs coverage Too much #inline documentation will clutter your code. Overdocumenting is as big a hindrance to #productivity as zero documentation. Only comment actual pockets of complexity in your codebase. Good documentation takes a measured approach. --- 🙂 Keep the language simple If something can be explained in fewer words, do so. Choose words that are easily understandable, #accessible and not needlessly verbose. Favor plain language, and stick to the point. Compare the following: /** Calculates the rotation of a vector */ vs. /** This function takes an angle and returns a new instance representing the original vector rotated by the angle */ Good documentation is economical. --- 📊 Correlate amount of details with complexity of code Ten lines of Java code making a REST call could be adequately explained in a single line. But a single line of C code with bitwise operators would probably need several lines of explanations. A simple function does not need a complex comment. Draft your docs so that they do justice to what a reader might need. Good documentation gives the right amount of information. --- Komment makes #code meaningful. What are your top #tips for writing good inline documentation? 💻 #DevOps #DocOps #AI #code #comments #KonnectWithKomment