How can you write maintainable code and avoid common language pitfalls?

We should define a common naming convention scheme a products in a company. All languages have default naming convention and it works well for all use cases. In case of package names, file names, class and method name company should stick to one format.

There are only two hard things in Computer Science: cache invalidation and naming things :) Naming variables, methods, classes etc. is the most important aspect of writing maintainable code and yet very difficult too. There are many coding standards available for each language and dev team should pick any one that the entire team agrees on. Or if need be create a new one but what is important is that entire team agrees on the standards and follows it Also, do not be afraid of using long descriptive names (as long as it clearly brings out purpose). Have seen many developers shy away from long names but a descriptive name is worth few lines of comment and goes a long way in making it easy to understand code at a later date

In my experience names should be as long as necessary. As engineers we lean toward keeping code dry, concise and short. l love shorter names, but don't be afraid to name a function or variable accurately. a good test is, if a new engineer on your team read the name would they know what it's purpose is WITHOUT reading the code. Example: let's say there is region endpoint in a relator api. getHomesForSaleByOwner(){....} vs. getHomesOwner(){...} Either way one would look for context, but one of these require memorization and is unintuitive and the other can just be read. The more complexed and dense your codebase the more this practice will become valuable.

Apart from naming conventions, we need to work closely with domain experts as to correctly naming our variables, functions, classes, and files. Understanding the domain entities, rules, processing, and workflows could help us construct consistent and meaningful names that could drive understanding of our codes structure that would also reflect correct the domain context and execution flow.

If someone new were to go through your code and read only the comments, would they end up understanding what's going on? Because that's often what will happen when skimming over someone else's work. One standard that I try to hold myself to is having at least one comment at the start of each distinct "paragraph" of code. This makes it quicker and easier to navigate to relevant sections and home in on what you actually need at the moment.

To start with, method and classname should be self explanatory. We can enforce the comments and documentation as part of PR process.

I would prefer avoid too much comments within the code base. Instead I would use: 1 - Developer executive summary of what the code based is all about, their algorithm used, flow of executions, and other issues that should be considered. 2- Use self-explanatory names that consistent and specific with the domain context. For example use work_order() instead of just order() that could ambiguous when cross domains. 3-use comments when they need be noticable to be significant importance

Personally, I believe that well named and well designed code is self documenting because it is well designed and at least somewhat intuitive. However having worked with larger teams, new engineers and cross functionally at scale, comments explaining classes, functions, variables becomes necessary. That being said there is no need to comment on mechanics of the language. The only other comments worth making in code are one where you go against established patterns for a good reason.

We should setup standard code formatters across orgnazistion. This leads to constent code and enabkles better reading maintenance of code. All IDEs support code formatters and sample configs are available all over internet. Same should be enforced in pipeline as hard check to avoid any leakage of bad styled code into ecosystem.

This should be mandatory, in your IDE and in your pipeline. Generally the more you can remove mental processing unrelated to problem solving the better. This includes visual patterns in format(indentation, single vs double quotes, etc) a situation that it reminds me of is when hearing your native language with a slight accent. Yes you can understand it, but when another person is explaining a complex topic, the accent could make it more challenging.

Once coding standards have been agreed upon for use by the organisation unit, appropriate language specific code formatters should be used to ensure code has a consistent look and feel. This also frees up the reviewers to only focus on business logic and not on the look and feel. Also since the tool does it for us, developers also benefit by getting the code aligned in a consistent manner with press of a few keys.

We should try to handle as much expected errors as possible but sometimes handling run time expectations could be overburden. having a standard error code and message list helps. As a matter of principle, your APIs should never return system exception messages as error response. those should be wrapped to send back a proper human language message and it should be logged as alert to enable tracing/debugging in the backend.

About 50% of a good application is dedicated to error handling. When issueing an error message text do not think what you know but consider the context of the person that is confronted with the message: what will he can understand so he can resolve the problem. Preferrably also describe the acrtion needed to remediate the problem. Useally this is also a kind of inline documentation.

Here are some of commonly used ways to achieve this - Follow Established Design Patterns: Utilise common design patterns (like Singleton, Factory, Observer, etc.) where appropriate. These patterns provide proven solutions for common problems in software design. -DRY (Don't Repeat Yourself): Avoid duplicating code. If you find yourself writing the same or very similar code multiple times, it’s usually better to abstract this into a function or class that can be reused. -Encapsulation: Keep your code organised into distinct modules, where each module is responsible for a specific functionality. This approach hides the internal workings of modules from other parts of your code, leading to better separation of concerns. and Many more.

This one is a bit tricky to get right by folks starting out in programming. Judgement to structure code such that it is re-usable and modular comes from experience and experience comes from bad judgements :) For folks starting out, reach out to senior developers for help and to review your design. Do not wait for the PR to get inputs on this. Also, design patterns (Builder, Factory, Strategy etc.) and design principles (DRY, SLAP, SOLID etc.) are your friend here which will help you structure your code in a way that it is easy to understand and re-usable.

A very important and often ignored exercise. Many a times, to meet delivery timelines we create small tech debts in code with the intention of revisiting and fixing them later. But we do not get around to doing it always and it grows We should refactor our code as and when we get some time. However for us to be confident that the re-factoring is not breaking anything we need a strong set of test cases which are testing the behaviour of software thoroughly. Without these test cases we will not get the confidence to refactor and improve the code base. Also, as and when we do version upgrades, we should use that as an opportunity to refactor the code and make it more maintainable by incorporating features of the higher version of language

If you get lost on what should be refactored I think S.O.L.I.D. principle are solid! Outside of a good guideline on how to structure a class. The two I find most useful are: Single use function - breaking down complex large functions into smaller single purpose ones -This is sure to shorten your debugging sessions. Dependency injection -Not only will this allow you to check crucial variables passed at the beginning of your code(establish a neat repeatable pattern), but it will also make writing test for your code simpler.

Today's top notch code is tomorrow's technical debt. There is no escaping that, so refactor at every possible moment, even if it "works".

Writing quality code is an acquired skill and one will have to go through bad code (self written and by others) before one gets to stage wherein they can write good quality code. As much a science as an art To improve one's code writing skills - Understand the language and its capabilities so that you use the right language feature for the task at hand - Understand that you are not writing good code for others alone but for your future self too. You will (at some point) revisit a piece of code written months (or years) ago - Read books about development. Understand established patterns which you can re-use It is a learning curve, an on-going journey but very enjoyable if one likes to write code

Consider using AI tools: To enhance software development with AI, consider tools like CodeGPT for code generation, Code Reviews with AI-based analyzers (e.g., CodeClimate), and testing tools like Diffblue Cover for automated test generation. Additionally, use version control systems like Git with AI integrations for better collaboration and code suggestions. Experiment with these tools to find what complements your workflow.