How do you write maintainable code?

Take the time and effort to invest in industry best practices. These standards, rules, and conventions pave the way for a pragmatic software artisan in developing a clean, maintainable, and robust codebase. Examples of such principles are SOLID, DRY, YAGNI, Fail Fast, among others. A footnote: Businesses should set money aside for refactoring.

I make sure to use descriptive names for variables and functions so that anyone reading the code can understand their purpose and usage without having to dig through the code. I include comments to explain complex parts of the code or to provide context. Additionally, I write documentation that outlines the overall structure and usage of the code, making it easier for others (or even myself in the future) to understand and work with it. I adhere to a consistent coding style throughout the project. This includes indentation, naming conventions, and other formatting rules. It makes the code visually consistent and easier to read.

Following coding standards/styles offers the following advantages: - Readability ?? - Error Reduction ? - Collaboration Efficiency ?? - Easy Maintenance & Modification ? - Code Consistency ?? Enhanced Scalability

In modern times, there's a multitude of IDE plugins available for upholding coding standards. These tools issue warnings during builds if standards are violated and often provide real-time suggestions by highlighting affected code sections. Utilizing such tools, like my preferred choice SONAR LINT, can be a valuable time-saving approach.

SOLID principles is a must have in any project. When you apply these concepts, by consequence you will have a testable and scalable code project. It’s also very important to define the architecture of the project. This estabilish the way that the project will grow and keep understandable for every person on the team.

"There are only two hard things in Computer Science: cache invalidation and naming things." -- Phil Karlton Compare all the files, variables, database tables as jars on a kitchen shelf with labels, if the labels do not identify what's inside the jar, it would take you ages before you find anything. Setting a coding standard for naming is equally important and adopt a ubiquitous language within the team. Any team member should be able to guess what would a file named even if they have not seen that earlier. In short:- - Name the files and variables in a self-explanatory way, so they don't need documentation - Adopt a common language, differentiate between. for example, "Service","Helper","Provider" in your codebase.

You may get inspiration for better naming from Domain Driven Design concepts. The logic represented by your code must be expressed with the terms from the business domain. Separating the system into Bounded Contexts, using the Ubiquitous Language should make code easier to understand.

If it's difficult to name a method, chances are it does too much, or behaves too differently depending on input, in many cases, that should lead to a refactor into smaller methods that are more easily understood. Converselty, when considering which of several appropriate names to chose, goWithThemAllAndEndUpWithAMethodNamePeopleCanUnderstandWhatDoes(). Do you have a filter method? Does it filter anyhting in particular? If it does, that might be part of the name.

Naming in coding holds immense significance. Selecting names for folders, files, variables, functions, and classes demands precision. They should convey purpose, be succinct, and maintain uniformity. Clear names facilitate understanding, aiding both developers and collaborators. Well-chosen names enhance code readability, aiding in error reduction and efficient troubleshooting.

Some coding tips 1-Remove the business logic or main code away from any framework code 2-Use version control to track and manage the changes and history of your code. 3-Document your code with comments and documentation that explain the functionality and design of your code. 4-Make a class/method do just one thing.

Maintenance is harder when you comment code as it is easier to be outdated. Focusing on clean code will help to *autodocument* the code.

I agree to this, I try to write comments as guidelines and structure before writing actual code. There will always be a "Who wrote this? Oh its me" moment :), hence its important to write comments for yourself and for others to clarify what is the code actually doing and why was it written in certain manner. There are some instances when the you are forced to write code in a "not so readable" manner for the needs of optimization or lower complexity. Clarify the intuition behind that in comments, such that it will be your voice for anyone reading the code later on.

Clear comments explain complex logic, assumptions, and intentions. Well-crafted comments improve code comprehension, aid future modifications, and enhance collaboration. Prioritize concise and meaningful comments over excessive detail. Misleading comments can lead to confusion and incorrect assumptions. If uncertain about a comment's accuracy, omitting it is preferable.

I think the ideal should be to write code, which is clear even without comments. This can be achieved by other techniques mentioned here: clear naming and formatting. However, in some cases this is unavoidable. As others mentioned, for example when code needs to be efficient rather than readable. In such cases it makes sense to comment. Any comment, should try to answer either “why this code is here”, “what it does” or both. Whichever is more relevant.

I disagree with some of these points, I think that good code turn comments into unecessary things. Of course we can have some cases of complex funcions for example that may be commented, but if you follow principles like single responsibility for example, you function will be straightfoward and yours purposes will be clear enough.

Refactoring is of major importance in keeping software maintainable and understandable, especially updating names to reflect their current function. Remember comments, update them to be accurate, if that's difficult, delete them, a wrong comment is worse than none at all. Ensure good test coverage of code to be refactored, write the tests before the refactor if there are none.

A moment of silence for all those refactor tickets that are lost in the "technical debt" graveyard of most backlogs. -------

You are constantly learning about the project while writing code. It usually happens that the decisions taken at start are not optimal. So it's completely normal and even crucial to revisit the initial design, and refactoring is always part of the development process.

What is "modular and reusable". At Google, people would write everything "as a web-service", as that's reusable. In Linux, people love to write console apps, as they can be easily reused in scripts. I write libraries. If you want to use the library, inside the memory of your web-service. Use it. If you want to create a console app, that does 1000 thousand of things, and also loads my library and maybe show 10 of the functions of my library by a "/something" or "/somethingElse"... do it. The real reusable code is not going to the the web-service of the console app, it doesn't matter how many times you are able to sell that to people who never coded themselves in their lives, or even how much money they make with the given "reusable" code.

The DRY principle is important here, using it correctly more so. Be careful not to introduce any unnecessary abstractions in the pursuit of modularity. Brewity and locality is more important than both reusability and modularity in allowing software to be easily understood and thus maintained and extended. Understand when something should be an elaborate, elegant, extensive system, and when half a screenful of tightly coupled mess can be preferred. It's easier, faster, cheaper and better to delete and re-implement half a screenful of "mess" to change a behavior than making hundreds of changes across tens of classes and methods to force an elegant system to do something it wasn't designed for.

Tests will be the watchguard for the code you write when you are away. There are two major aspects I see to writing test cases - Firstly, the help you to easily test the code in isolation (unit tests) and with simulated integration (integration tests) for multiple scenarios - Its more resourceful to write test cases than manually running the test cases multiple times. - There "will" be changes to your code in future, and the person making changes might not be aware of all scenarios the code should run for. Automated test cases keep a tab that existing functionality is not broken in such scenarios.

Documentation is undeniably the most important part of any project. A thorough document eases a lot of processes around the project including knowledge transfer, support and enhancements. For me, the document is not just limited to architectural diagrams or LLDs. Descriptive comments, meaningful variables, and unit tests also contribute to the same.

For juniors and mid level developers, as a mentor I saw some cases of developers that skip steps. So, make sure that you have consistently learned basic principles of algorithms and computer architecture.

Always follow the SOLID principle while writing the code. SOLID is an acronym for five design principles: S - Single Responsibility Principle: Each class or module should have only one reason to change. O - Open/Closed Principle: Software entities should be open for extension but closed for modification. L - Liskov Substitution Principle: Subtypes must be substitutable for their base types without affecting program correctness. I - Interface Segregation Principle: Clients should not be forced to depend on interfaces they do not use. D - Dependency Inversion Principle: High-level modules should not depend on low-level modules; both should depend on abstractions.

The most maintainable code is the code that never needs to be maintained. I can say that with total confidence. I wrote some code between 2008 and 2010... at home... to which I took the library to work and put it to use. I never gave them the code. I was told that "giving the code would allow them to add new resources" when I said: I am just implementing an existing interface. Anything you want to add to this code, pertains somewhere else. Well... many people told me my code was not professional and would be replaced soon. They tried, many times, to use more "professional" libraries than mine. And, guess what, my code is still there, without a single crash that was not cause by lack of real resources, for more than 13 years.