How do I write clean and maintainable code

The key to maintainable code is encapsulation.

Give every piece of functionality an interface. All the other code that uses it must use it through that interface. The interface should be as generic as possible and not leak internal implementation details.

This makes everything better: you can test each piece of functionality in isolation, and use mocks when you test the code that depends on that piece. You can replace the implementation without changing the interface or the other code that uses it. You can have different people work on different parts of the codebase without merge conflicts.

The other biggest piece of advice I can give is to use a statically typed language. Sorry, Python type hints are not good enough. Maintaining a large codebase, years after it was written by other people, is far easier with a static type system. That's why dynamic languages added type hints in the first place, although they can never match what statically typed languages had from day one. Don't sacrifice that for ease of implementation or speed of prototyping: over the long run you will spend far more time running code, debugging code, and maintaining code, than you will spend writing new code. Front-load all that effort by using a static type system.

People default to documentation as the best way to write clear code but documentation is a no win task. It's never kept up to date, it's never clear enough and of course it's time consuming.

I favor the building house approach.

Generally, describe what you want to accomplish in a simple language outline. Create a blueprint in the same idea as a house builder would get to build a house and write code that self documents.

1) Descriptive names for whatever you need to name. Long names are ok.

2) No monolithic code. Break it up.

3) Choose clarity over brevity

4) No magic numbers, don't use hacks

5) No cute coding, coders want to show how smart they are by writing code that does a lot within a few lines. It might be fun for the coder but it's useless for long term production code.

6) Code as if a newbie will read your code. Rework if you need to speed up the code.

7) Always code as if you expect someone else will read your code. This will keep you from doing quick "temp" changes that will never get fixed.

8) Follow an established coding style. Don't reinvent the wheel

9) Sometimes there is no choice; use in-code comments as needed but don't over use them since you will need to update them later.

Most of all, talk to your other code partners and decide the best style that works for the group. Don't be a one man coding machine. Work with your team.

It might seem like you are doing a lot of work for some one else's benefit but I guarantee that you are not.

Something that happens a lot is that you'll need to rework your code a few months later and you will have no clue what you did. Writing clear code will help you immensely as you try to figure out what you did and what you need to do to fix the problems.

IMO Maintainable code relies on 2 things: Readbility and Documentation.

How these are achieved is the matter of entire libraries worth of books, and everyone has a different opinion. Style guides are nice, but it is perfectly possible to follow every single rule in a style guide, and still write unmaintainable spaghetti-code, because readbility goes beyond what code and comments look like.

It is easily as (if not more) important, how code is organised. I suggest watching https://www.youtube.com/watch?v=5ZKvwuZSiyc for a good example.

So unfortunately, I do not know a simple answer to your question, I can only tell you what worked for me so far:

1. Try the simple solution first

2. Beware of premature optimization and do not optimize until performance was measured

3. Write Documentation while/before the implementation. At the very least keep a "dev-diary" outlining the code in broad strokes.

4. Beware of premature imposition of structure. Build a few parts that fit together, and impose structure (modules, classes) when it becomes apparent that they are justified.

5. Name things well. Not every variable needs to be `ThingOfThingAggragatorWallabaloogaMessengerFactory", and neither should there be a global named `f_zT`. If it has local scope and is obvious from context, single-letter names are okay.

6. It matters less what style is used, as long as it is used consistently (usually within a team)

7. Avoid tiny dependencies. I don't need a library for something I can write at 3AM with no coffee in my system (left-pad anyone?)

Those are some of the rules I try to adhere to. Not all of them will work in every scenario, none of them are set in stone. As outlined above, maintainability in code is a tricky and unsolved topic.

Maintainable code is a fools errand people just need the lingo for the interview, people don't stay at the same job long enough to really worry about it long term. People ship the one to throw away then the next devs rewrite everything their foredevs wrote. Languages, databases and standards are moving targets and today's best practice is tomorrow's antipattern.

If you want to ensure that you hire devs who have longevity in your product only hire devs who have worked in the same place long enough to pay for their coding choices and ask them for specific times they had technical debt and what steps they took to remedy the problem. You will find out more by letting them talk.