Writing Code Documentation

🌎 Designing Cross-Cultural And Multi-Lingual UX. Guidelines on how to stress test our designs, how to define a localization strategy and how to deal with currencies, dates, word order, pluralization, colors and gender pronouns. ⦿ Translation: “We adapt our message to resonate in other markets”. ⦿ Localization: “We adapt user experience to local expectations”. ⦿ Internationalization: “We adapt our codebase to work in other markets”. ✅ English-language users make up about 26% of users. ✅ Top written languages: Chinese, Spanish, Arabic, Portuguese. ✅ Most users prefer content in their native language(s). ✅ French texts are on average 20% longer than English ones. ✅ Japanese texts are on average 30–60% shorter. 🚫 Flags aren’t languages: avoid them for language selection. 🚫 Language direction ≠ design direction (“F” vs. Zig-Zag pattern). 🚫 Not everybody has first/middle names: “Full name” is better. ✅ Always reserve at least 30% room for longer translations. ✅ Stress test your UI for translation with pseudolocalization. ✅ Plan for line wrap, truncation, very short and very long labels. ✅ Adjust numbers, dates, times, formats, units, addresses. ✅ Adjust currency, spelling, input masks, placeholders. ✅ Always conduct UX research with local users. When localizing an interface, we need to work beyond translation. We need to be respectful of cultural differences. E.g. in Arabic we would often need to increase the spacing between lines. For Chinese market, we need to increase the density of information. German sites require a vast amount of detail to communicate that a topic is well-thought-out. Stress test your design. Avoid assumptions. Work with local content designers. Spend time in the country to better understand the market. Have local help on the ground. And test repeatedly with local users as an ongoing part of the design process. You’ll be surprised by some findings, but you’ll also learn to adapt and scale to be effective — whatever market is going to come up next. Useful resources: UX Design Across Different Cultures, by Jenny Shen https://lnkd.in/eNiyVqiH UX Localization Handbook, by Phrase https://lnkd.in/eKN7usSA A Complete Guide To UX Localization, by Michal Kessel Shitrit 🎗️ https://lnkd.in/eaQJt-bU Designing Multi-Lingual UX, by yours truly https://lnkd.in/eR3GnwXQ Flags Are Not Languages, by James Offer https://lnkd.in/eaySNFGa IBM Globalization Checklists https://lnkd.in/ewNzysqv Books: ⦿ Cross-Cultural Design (https://lnkd.in/e8KswErf) by Senongo Akpem ⦿ The Culture Map (https://lnkd.in/edfyMqhN) by Erin Meyer ⦿ UX Writing & Microcopy (https://lnkd.in/e_ZFu374) by Kinneret Yifrah

🧩 Why I stopped writing clever code. I started coding as a competitive programmer in high school. We were given five hours to solve five to ten hard algorithmic problems. Speed from thought to code matters. Code brevity matters. Even my typing speed matters. When I started working in a real company, I took a secret pride in writing short and clever codes, especially those magical one-liners. It made me feel quick and smart. I thought that it was a mark of expertise. But after the 17th "What does this line do?" DM, I felt that the problem was not my teammate's intelligence but rather my own code. If only me can understand and maintain the code, I haven't really built a system, I've made a puzzle 😂 🧑💻 I learned that readable code is about future-proofing my work: - The best code is written for humans first, computers second. - I'll thank myself 6 months later when I come back to fix a bug at 2am. - My new teammates will onboard faster. - Bugs are also caught earlier because the review is easier. ⁉️ How to make your code more readable? - Use clear, descriptive variable and function names. No more x, foo, or doStuff. - Write comments, but not essays. Explain the “why,” not the obvious “what.” - Break down complex logic into smaller, well-named functions. - Stick to consistent formatting and style. Clever one-liners may win you programming contests, but readable code wins you trust from your team 😉

Best Practices for Writing Clean and Maintainable Code One of the worst headaches is trying to understand and work with poorly written code, especially when the logic isn’t clear. Writing clean, maintainable, and testable code—and adhering to design patterns and principles—is a must in today’s fast-paced development environment. Here are a few strategies to help you achieve this: 1. Choose Meaningful Names: Opt for descriptive names for your variables, functions, and classes to make your code more intuitive and accessible. 2. Maintain Consistent Naming Conventions: Stick to a uniform naming style (camelCase, snake_case, etc.) across your project for consistency and clarity. 3. Embrace Modularity: Break down complex tasks into smaller, reusable modules or functions. This makes both debugging and testing more manageable. 4. Comment and Document Wisely: Even if your code is clear, thoughtful comments and documentation can provide helpful context, especially for new team members. 5. Simplicity Over Complexity: Keep your code straightforward to enhance readability and reduce the likelihood of bugs. 6. Leverage Version Control: Utilize tools like Git to manage changes, collaborate seamlessly, and maintain a history of your code. 7. Refactor Regularly: Continuously review and refine your code to remove redundancies and improve structure without altering functionality. 8. Follow SOLID Principles & Design Patterns: Applying SOLID principles and well-established design patterns ensures your code is scalable, adaptable, and easy to extend over time. 9. Test Your Code: Write unit and integration tests to ensure reliability and make future maintenance easier. Incorporating these tips into your development routine will lead to code that’s easier to understand, collaborate on, and improve. #CleanCode #SoftwareEngineering #CodingBestPractices #CodeQuality #DevTips

Strategy is useless to AI until you turn it into instructions it can actually read. (Part 3 of my series on rebuilding our website with Claude Code.) This is how we scaled, and how we made AI useful without drowning in rework. Here is what we learned fast: if your strategy lives in your head, or in a doc nobody opens outside of your environment, your AI is working blind. It guesses, you correct, it guesses again. Writing the guidelines down is what broke that loop. So we didn't write one giant prompt. We wrote guidelines, the way you would onboard three human specialists, and committed them to GitHub so Claude reads them automatically at every step of the build. For us, that was three sets of instructions. SEO and Content. We started with how we talk about our product: what we do, what resonates, how we want to be positioned. Then we turned our research, competitive analysis and customer feedback, into rules Claude could apply on every page, plus a set of tests it runs against each one. We concentrated on technical SEO a lot here and made sure we were specific, and everything was testable. Design. This was huge for consistency. We built a style guide Claude has to read before it writes a single line: our colors as variables, our typography, our buttons, our components. Strict on purpose. Never invent class names. Never hardcode a color. When we made a new component, we decided what stayed and folded it into the guide, so Claude kept reusing what we already had. Every correction got written down so it never happened twice. One example: I kept deleting little uppercase labels above our headings, so it became a rule, and Claude never added one again. And because Claude is weak at UX on its own (more on that later), we spelled out how we wanted things laid out and to function. Development. The dev guidelines covered how to build a feature, how to handle errors, and what "done" means: requirements met, conditions checked, tests passing before anything ships. It writes its own tests for the APIs and other moving parts, then reruns them before every deployment, so something that worked last week doesn't quietly break this week. Here is why this mattered. Because it all lives in the codebase, any agent working in there picks up the rules, and the work that came before, automatically. Nobody has to remember to paste in context. It is just there. Claude rated our setup in the top 1 to 2% of its users for how thoroughly the rules, plans, and memory were documented. These are the same things I have been working with companies to implement through Product Operations that also make human teams work: write down how you do things, keep it where people can see it, and improve it every time you learn something. Give your AI the same guardrails you would give a new hire, and put them where the work actually happens. Next up: a closer look under the hood, how we run AI coding agents like an engineering team instead of a chat window.

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

Master these strategies to write clean, reusable code across all data roles. Here is how you keep your code clean, efficient, and adaptable:  1. 𝗠𝗼𝗱𝘂𝗹𝗮𝗿 𝗗𝗲𝘀𝗶𝗴𝗻: Break down your code into distinct functions that handle individual tasks. This modular approach allows you to reuse functions across different projects and makes debugging far easier.       2. 𝗗𝗼𝗰𝘂𝗺𝗲𝗻𝘁𝗮𝘁𝗶𝗼𝗻: Comment your code clearly and provide README files for larger projects. Explain what your functions do, the inputs they accept, and the expected outputs. This makes onboarding new team members smoother and helps your future self understand the logic quickly.       3. 𝗣𝗮𝗿𝗮𝗺𝗲𝘁𝗲𝗿𝗶𝘇𝗮𝘁𝗶𝗼𝗻: Use parameters for values that could change over time, such as file paths, column names, or thresholds. This flexibility ensures that your code is adaptable without requiring major rewrites.       4. 𝗜𝗻𝘁𝗲𝗻𝘁𝗶𝗼𝗻𝗮𝗹 𝗡𝗮𝗺𝗶𝗻𝗴: Variable, function, and class names are your first layer of documentation. Make them descriptive and consistent.       5. 𝗖𝗼𝗻𝘀𝗶𝘀𝘁𝗲𝗻𝘁 𝗦𝘁𝘆𝗹𝗲: Adopt a coding standard and stick to it. Whether it’s the way you format loops or how you organize modules, consistency makes your code predictable and easier to follow.       6. 𝗘𝗿𝗿𝗼𝗿 𝗛𝗮𝗻𝗱𝗹𝗶𝗻𝗴: Include error handling in your functions. Use try-except blocks to catch exceptions, and provide informative messages that indicate what went wrong and how to fix it.       7. 𝗧𝗲𝘀𝘁𝗶𝗻𝗴: Implement unit tests to verify that each function performs as expected. This proactive approach helps identify issues early and ensures that changes don’t introduce new bugs.       8. 𝗩𝗲𝗿𝘀𝗶𝗼𝗻 𝗖𝗼𝗻𝘁𝗿𝗼𝗹: Use Git or another version control system to manage changes to your code. It allows you to track progress, roll back mistakes, and collaborate seamlessly.       9. 𝗖𝗼𝗱𝗲 𝗥𝗲𝘃𝗶𝗲𝘄𝘀: Encourage peer reviews to catch potential issues, share best practices, and foster a culture of collaborative learning.      10. 𝗥𝗲𝘃𝗶𝗲𝘄 𝗮𝗻𝗱 𝗥𝗲𝗳𝗮𝗰𝘁𝗼𝗿: Review your code after a break, seeking opportunities to simplify and improve. Refactoring is your path to more robust and efficient code.   Whether writing small SQL queries or building large Python models, a clean coding style will make you a more efficient analyst. It’s an investment that will pay off in productivity and reliability. What’s your top tip for writing reusable code? ---------------- ♻️ Share if you find this post useful ➕ Follow for more daily insights on how to grow your career in the data field #dataanalytics #datascience #python #cleancode #productivity

I’ve seen teams argue for hours about tabs vs spaces, but skip the basics that actually make code easier to read and maintain. Here’s what really moves the needle for Python projects: 1) Write code that explains itself. Clear names and small functions solve half the pain. 2) Treat PEP 8 as a baseline, not a religion. Consistency matters more than strictness. 3) Add type hints. They save time, catch silly mistakes, and make the code easier for teammates and tools to reason about. 4) Keep functions focused. If it’s hard to describe what it does in one line, it’s trying to do too much. 5) Handle errors thoughtfully. Catch what you expect and log what you need. 6) Document the “why,” not the obvious. 7) Clean imports, meaningful tests, and no random magic values sprinkled around. These simple habits make Python code kinder to whoever reads it next -including future you. #python #codingstandards #codequality #cleancode #bestpractices #programmingtips Follow Sneha Vijaykumar for more... 😊

Some best practices for writing code-comments. Often, comments should only answer questions code can't (e.g. the "why") Good code should read like a well-written prose, and inline comments act as its annotations. Yet, writing meaningful comments is often overlooked, considered a secondary or trivial task. But a poor or missing comment can confuse or mislead the reader, causing more harm than no comments at all. Ellen Spertus laid out an excellent framework for how to get code comments right: https://lnkd.in/gKjvHd4N: Rule 1: Comments should not duplicate the code. Rule 2: Good comments do not excuse unclear code. Rule 3: If you can't write a clear comment, there may be a problem with the code. Rule 4: Comments should dispel confusion, not cause it. Rule 5: Explain unidiomatic code in comments. Rule 6: Provide links to the original source of copied code. Rule 7: Include links to external references where they will be most helpful. Rule 8: Add comments when fixing bugs. Rule 9: Use comments to mark incomplete implementations. Rule 1: Avoid Redundancy Comments shouldn't echo the code. Redundant comments are mere noise. A comment like i = i + 1; // Add one to i doesn't help anyone. It only distracts. Rule 2: Clarity Over Comments If you find yourself writing a comment to make a complicated block of code clear, stop. Rethink and refactor the code first. Good variable naming often obviates the need for comments. Rule 3: If It's Complicated to Comment, It's Likely Wrong If you can't write a clear comment for a piece of code, that might be a red flag. Maybe the code is too convoluted or the logic too tangled. Rewrite it. Rule 4: Clarify, Don't Confuse Don't let your comments turn into riddles. If a comment generates more questions than it answers, it's a bad comment. Rule 5: Comment Unidiomatic Code Sometimes you have to break the usual rules for special cases. When you do, explain why. A well-placed comment can prevent future devs from "fixing" code that isn't broken. Rule 6: Attribute Copied Code If you're lifting code from Stack Overflow/GPT or any other source, provide a link. This is good for both context and complying with licenses. Rule 7: Link to External References When your code adheres to a particular standard or responds to an RFC, say so in a comment and link to it. Rule 8: Comment Bug Fixes When you fix a bug, leave a breadcrumb for future developers. This might be as simple as a comment pointing to an issue number or explaining the bug's behavior. Rule 9: Mark Incomplete Code Sometimes you have to commit code with known limitations. Use a standard TODO format to highlight these. Mention the technical debt and perhaps link to an issue tracker. Conclusion Comments don't fix bad code; they complement good code. When done poorly, they obfuscate. Keep these guidelines in mind #programming #developers #code #work 

🛠️ In the journey to avoid the chaos 🌀 of complicated code, as shown in the picture, here’s how we can excel in creating clean, maintainable code with excellent documentation📚: 1️⃣ **Clarity Over Cleverness**: Write code as if the next maintainer is a 🔍 detective piecing together a mystery. Simple and clear beats smart and obscure. 🧠 2️⃣ **Self-documenting Code**: Choose variable and function names that tell a story 📖. If it reads like a novel, you're on the right track. ✅ 3️⃣ **Comment Wisely**: Comments should be the 'why', not the 'what'. They're the subtitles 🗨️ to your code's movie. 🎬 4️⃣ **Consistent Style**: Stick to a coding standard 🎯 that everyone understands. It's like a dress code for your code! 👔 5️⃣ **Refactor Regularly**: Keep your code in tip-top shape 🏋️♂️. It's the gym routine for your codebase! 6️⃣ **Comprehensive Documentation**: Keep a diary 📓 of your code's life. It's the legend to your treasure map! 🗺️ 7️⃣ **Peer Reviews**: Regular code reviews are like health check-ups 🩺 for your code. Catch those bugs 🐞 early! Let's make our code a joy to read, understand, and enhance. For code not only to work 🖥️ but to be understood by all who follow. 🌈 #CleanCode #SoftwareDevelopment #BestPractices #CodeMaintenance

The problem with keeping code and documentation separate. It tends to diverge over time. So most software documentation should be replaced with highly readable code and tests. However, no matter how readable the code is, it doesn’t give us the context behind why the code exists in the form that it does. To address this software engineering teams should be keeping Architecture Decision Records (ADRs). These are lightweight documents that capture important architectural decisions along with the when, how and why of the decision. ADRs are particularly useful for agile projects where not all the decisions will be made at once and long lifetime projects where a new person joining the team, or someone who hasn’t worked on part of the project recently, will need to understand the rationale and consequences of a decision that has been made in the past. An ADR should record: 1. When the decision was made. 2. The status of the ADR (proposed, accepted, rejected, etc.). 3. The current context and business priorities that relate to the decision. 4. The decision and what will be done because of the decision. 5. The consequences of making the architectural decision. ADRs are best stored in the revision control system alongside the code that they relate to, keeping the context with the code.