Improving Code Readability in Large Projects

Code is the product. How do you prevent a 1M+ LoC Python library, built by thousands of contributors, from collapsing under its own weight? In transformers, we do it with a set of explicit software engineering tenets. With Pablo Montalvo, Lysandre Debut, Pedro Cuenca and Yoni Gozlan, we just published a deep dive on the principles that keep our codebase hackable at scale. What’s inside: – The Tenets We Enforce: From One Model, One File to Standardize, Don't Abstract, these are the rules that guide every PR. – "Modular Transformers": How we used visible inheritance to cut our effective maintenance surface by ~15× while keeping modeling code readable from top to bottom. – Pluggable Performance: A standard attention interface and config-driven tensor parallelism mean semantics stay in the model while speed (FlashAttention, community kernels, TP sharding) is a configurable add-on, not a code rewrite. This matters for anyone shipping models, contributing to OSS, or managing large-scale engineering projects. It’s how we ensure a contribution to transformers is immediately reusable across the ecosystem (vLLM, ggml, SGLang, etc.). Read more on the Hugging Face blog

🧩 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 😉

🚨𝐀𝐯𝐨𝐢𝐝 𝐃𝐞𝐞𝐩 𝐍𝐞𝐬𝐭𝐢𝐧𝐠 𝐢𝐧 𝐀𝐁𝐀𝐏 – 𝐈𝐦𝐩𝐫𝐨𝐯𝐞 𝐑𝐞𝐚𝐝𝐚𝐛𝐢𝐥𝐢𝐭𝐲 𝐚𝐧𝐝 𝐌𝐚𝐢𝐧𝐭𝐚𝐢𝐧𝐚𝐛𝐢𝐥𝐢𝐭𝐲🚨 In SAP ABAP (and any programming language), deeply 𝒏𝒆𝒔𝒕𝒆𝒅 𝑰𝑭 statements inside loops can make your code difficult to read and maintain. While it may seem efficient to stack conditions in a single block, it often leads to: 👎 𝐂𝐨𝐧𝐬 𝐨𝐟 𝐃𝐞𝐞𝐩 𝐍𝐞𝐬𝐭𝐢𝐧𝐠: ▪ 𝐑𝐞𝐝𝐮𝐜𝐞𝐝 𝐑𝐞𝐚𝐝𝐚𝐛𝐢𝐥𝐢𝐭𝐲: Deeply nested conditions force you to read through layers of logic to understand what's going on. It’s harder for others (or even yourself) to follow the flow when revisiting the code. ▪ 𝐇𝐢𝐠𝐡𝐞𝐫 𝐌𝐚𝐢𝐧𝐭𝐞𝐧𝐚𝐧𝐜𝐞 𝐂𝐨𝐦𝐩𝐥𝐞𝐱𝐢𝐭𝐲: When adding more conditions or logic later, maintaining nested structures becomes a challenge. It increases the risk of missing important logic or creating new bugs. ▪ 𝐃𝐢𝐟𝐟𝐢𝐜𝐮𝐥𝐭 𝐃𝐞𝐛𝐮𝐠𝐠𝐢𝐧𝐠: Tracking down bugs in nested code requires stepping through each condition, which makes debugging time-consuming and error-prone. To avoid these issues, it's better to "𝒆𝒙𝒊𝒕 𝒆𝒂𝒓𝒍𝒚". This technique simplifies the logic by handling edge cases first, allowing the main logic to run in a clear, linear fashion. Exiting early can be achieved using statements like 𝘾𝙃𝙀𝘾𝙆, 𝑪𝑶𝑵𝑻𝑰𝑵𝑼𝑬, and 𝑹𝑬𝑻𝑼𝑹𝑵. 👍 𝐏𝐫𝐨𝐬 𝐨𝐟 𝐄𝐱𝐢𝐭𝐢𝐧𝐠 𝐄𝐚𝐫𝐥𝐲: ▪ 𝐂𝐥𝐞𝐚𝐫 𝐚𝐧𝐝 𝐂𝐨𝐧𝐜𝐢𝐬𝐞 𝐋𝐨𝐠𝐢𝐜: By handling conditions at the start of a loop and exiting when they aren’t met, the logic flow is cleaner and more readable. Each part of the code has a specific purpose, making it easier to follow. ▪ 𝐈𝐦𝐩𝐫𝐨𝐯𝐞𝐝 𝐌𝐚𝐢𝐧𝐭𝐚𝐢𝐧𝐚𝐛𝐢𝐥𝐢𝐭𝐲: The structure is flatter, allowing you to easily add new conditions or logic without disrupting existing code. Future developers (or your future self) will thank you for writing code that’s easy to maintain. ▪ 𝐄𝐟𝐟𝐢𝐜𝐢𝐞𝐧𝐭 𝐃𝐞𝐛𝐮𝐠𝐠𝐢𝐧𝐠: You can quickly identify issues by seeing which conditions cause an early exit, making debugging faster and more straightforward. 💡 𝗞𝗲𝘆 𝗧𝗮𝗸𝗲𝗮𝘄𝗮𝘆: By exiting early, you avoid deeply nested conditions and loops, leading to code that is cleaner, easier to read, and more maintainable. Keep your code simple, efficient, and understandable by handling conditions at the top of your loops. #SAPABAP #CleanCode #ABAPBestPractices #ExitEarly #CodeReadability #TechTips

The most important prompt when coding with AI: "Scan the codebase for files over 600 lines." Then: "Modularize X to improve maintainability, scalability, and ease of editing." Most people blame the AI when their code breaks. But 90% of the time, the problem isn't the model, it's the codebase. Large files are the silent killer of AI-assisted development. Here's what actually happens when you ask an AI to edit a 2,000-line file: → The model can't hold all the logic in its context window at once → It misses dependencies between functions scattered across hundreds of lines → It "hallucinates" fixes that conflict with code it can't fully see → You spend more time debugging AI output than you saved by using it I ran a scan on one of our projects and found 10 files over 600 lines. The worst offender? A views.py at 2,438 lines. That single file was the root cause of most of our AI-assisted coding frustrations. The solution is simple: modularize before you prompt. Break large files into focused, single-responsibility modules. Keep each file under 300-500 lines. Group related functions together. Give files clear, descriptive names. Once you do this: → AI understands your code fully, no missing context → Changes are isolated, one edit doesn't cascade into 5 bugs → Code reviews become easier, for both humans and AI → Your prompts get simpler, "refactor this file" actually works This is the difference between fighting your AI tools and flowing with them. Try it on your next project. Scan for large files first. Modularize. Then prompt. You'll never go back.

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

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... 😊

Your dev team doesn’t need more code. It needs better systems. This week, I reviewed one of our codebases. What I saw is common across fast-moving startups: – Repos with no consistent naming – Missing or outdated READMEs – Old branches piling up – Hard-coded credentials – No CI checks, tests, or structure – Massive, unmanageable files None of this is about bad developers. It’s about missing systems. Here’s what we did—and what any dev team can implement fast: 1. Organize your repos Clear names. Clean branches. Set main as the default. Protect it. 2. Write solid docs Every repo should explain what it is, how to run it, and what it does. Use ChatGPT to help. 3. Automate the basics Use GitHub Actions. Lint. Run tests. Scan dependencies. Don’t trust code that hasn’t passed checks. 4. Improve PR quality Good titles. Clear descriptions. Screenshots. Auto-delete merged branches. Require reviews. 5. Refactor big files Modular, readable code wins every time. Don’t mix config with logic. Use env variables and lock files. 6. Use AI as your co-pilot I uploaded a full codebase to ChatGPT. In 10 minutes, it flagged issues, suggested tests, and surfaced risks we missed. That’s leverage. The real unlock? Mindset. This isn’t red tape. It’s freedom. With checks in place, I can approve PRs from my phone—because I know the basics are solid. Startups move fast. But only if your codebase can keep up. What dev practice has saved your team the most time or stress? --- Enjoy this? ♻️ Repost it to your network and follow Kevin Henrikson for more. Weekly frameworks on AI, startups, leadership, and scaling. Join 1800+ subscribers today: https://lnkd.in/gstGkhJF

Sometimes, we have code that works but has problems. Maybe it is too complicated. Maybe it has methods that are too long and do too many things. Or maybe it is hard to read because things are named badly. In any of these cases, the answer is to refactor the code. Refactoring is defined as “restructuring existing source code to improve its design, structure, and implementation without changing its external behavior or functionality.” Usually, this involves making a series of small changes that gradually improve the code. Before you start any refactoring, you need to make sure you have unit tests that verify the external functionality you need to preserve. A broken test means you need to roll back the change and try again. If you don’t have adequate tests, write them before you start. What if you don’t have tests, and the code is so badly structured that you can’t write them? In that case, you can look at Michael Feathers’ great book, “Working Effectively With Legacy Code” (https://lnkd.in/gCSvihYP). Feathers defines legacy code as any code without unit tests. This book has a lot of techniques for relatively safe refactorings that get the code into a state where you can write tests. Refactoring steps don’t need to be huge. In fact, it is better if they are not. If you make a small change, it is easier to roll back if you break something. Then you can make the next small change. Very often, a refactoring step may seem to make the code woaxrse, but that is okay. It’s like rearranging the furniture in a room by moving one piece at a time. In the middle of the process, you might be able to sit in the chairs, but the room would look messy. Possibilities for useful refactorings are endless. Maybe you find a variable name that is confusing. Then you can improve things by renaming it. Perhaps you find a confusing method, and can break out part of it into a well-named smaller method. You might extract or inline a variable. At a larger scale, you might want to extract an interface or a superclass, or move a function from one class to another, or into its own class. I will try to delve into some of these more deeply. In the meantime, Martin Fowler’s “Refactoring: Improving the Design of Existing Code” is the seminal resource. (https://lnkd.in/gVe6tDFm).

Hey Scouts! 🦅 Have you ever heard of the “Boy Scout Rule” for cleaner code? When developing software, one of the most effective ways to maintain a healthy codebase is to apply what’s often called the “Boy Scout Rule”: leave the code better than you found it. This doesn’t mean undertaking grand redesigns every time you touch a file, but rather making small, incremental improvements as you work. Maybe it’s extracting a function into a more descriptive name, removing a dead variable, or rewriting a tangled conditional in a clearer way. These seemingly minor changes accumulate and keep technical debt at bay. Practicing this rule ensures that every interaction with your codebase is an opportunity for enhancement, not just a means to deliver a new feature. Over time, you and your team will notice that code feels easier to read, navigate, and adjust. This steady, disciplined commitment to continuous improvement helps foster a culture of craftsmanship, ensuring that your code doesn’t just work, it evolves gracefully as the system grows and matures.

Every software developer thinks “Why is the code so messy ?”, “Why didn’t the code author think about this ?”, “Why does the service lack tests ?”, “What a ridiculous variable name ?”. But does anyone go an extra mile to fix this ? 😣 😠 The answer is No. We are so busy developing new features, we accept things the way they are, & don’t work on Tech debt. This eventually slows the development. ⏲ ⏲ If you are in a similar situation, then you should definitely adopt the Boys Scout rule. Let’s understand how you can improve the quality of your software by applying this rule. 📚 📚 Boys Scout rule says - “Always leave the camp ground cleaner than you found it”. If you find mess on the ground, you clean it up regardless of who might have made it. You intentionally improve the environment for the next group of campers. 🌐 🌐 When you apply the same principle to programming, you refactor the existing code while developing new features. You work on improving the surrounding code and it doesn’t have to be a huge improvement. You shouldn’t make the code worst with your contributions. Here are few ways in which you can apply the Boy Scout rule  :- 1️⃣ Code smells - Remove redundant code, unused variables, unused imports. 2️⃣ Refactoring - Remove code duplication, improve readability and reduce complexity. 3️⃣ Test automation - Add unit tests and integration tests. 4️⃣ Documentation - Improve the comments, include more details, add run books. 5️⃣ Knowledge sharing - Share your expertise with the team and encourage everyone to follow the same practice. By incorporating these practices, you can contribute to a cleaner, more maintainable codebase and avoid the accumulating technical debt. When you apply small improvements consistently, it impact is significant and improves the overall quality of your codebase. 🚀 🚀 Let me know in the comments below what else can we include to improve the code quality while applying the Boy Scout rule. Also, if you have applied this rule in the past, share your experience in the comments. 📢 📢 For more such posts, follow me. #refactoring #codingskills #softwareengineering #softwaredevelopment