How to Write Clear and Accurate Code Comments

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

Ever looked at old code and thought, "Who wrote this? And why?", only to realize it was YOU? 🤦♂️ That’s why internal documentation is a lifesaver! It turns cryptic code into clear, maintainable logic. Here’s how to document like a pro: 🔹 File-Level Documentation: Start with a high-level summary. What’s the purpose of this file? Is it handling authentication, processing payments, or managing user data? Give future developers (including yourself) a clear idea of what’s inside before they even start reading the code. 🔹 Function-Level Documentation: Each function should answer three key questions: ✅ What does this function do? (Describe its purpose) ✅ What inputs does it take? (List expected parameters & data types) ✅ What does it return? (Explain the output) This way, anyone can understand what’s happening—without guessing! (see example in the image below 👇) 🔹 Line-Level Comments: Not every line needs a comment, but complex or non-obvious logic does. Example: # 𝘜𝘴𝘪𝘯𝘨 𝘣𝘪𝘵𝘸𝘪𝘴𝘦 𝘈𝘕𝘋 𝘵𝘰 𝘤𝘩𝘦𝘤𝘬 𝘪𝘧 𝘯𝘶𝘮𝘣𝘦𝘳 𝘪𝘴 𝘦𝘷𝘦𝘯 (𝘱𝘦𝘳𝘧𝘰𝘳𝘮𝘢𝘯𝘤𝘦 𝘰𝘱𝘵𝘪𝘮𝘪𝘻𝘢𝘵𝘪𝘰𝘯) if num & 1 == 0: print("Even number") Even if it seems obvious today, your future self (or a teammate) will appreciate the clarity. 🚀 The Goal? Make your code self-explanatory so that debugging, onboarding, and refactoring become painless. This is just one of the many best practices I cover in my new Become a Better Data Engineer course. If writing cleaner, more maintainable code is on your to-do list, this course is for you 🚀 https://bit.ly/3CJN7qd Who else has been saved by well-documented code? Share your stories below! 👇 #DataEngineering #CleanCode #InternalDocumentation

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