Good code is like a love letter to the next developer who will maintain it

> just like a really good book was much harder for the author than it was for you, the reader.

Now, I suppose this could work for a nested narrative novel, where the reader is meant not to just read the book, but to rewrite and expand it as they're reading it. Adding new ideas, new sub stories on the way. Think 100 Years of Solitude blended with Italo Calvino's Invisible Cities.

Seems like the [*]Bible is a good literary example of an async collaboration similar to code: notoriously hard to interpret, and full of dubious historical information and contradictions.

I know that Christians call it the "good book", but most of them don't use the word "good" in the same way they'd use it to describe a Nabokov or Eco novel.

[*] or most ancient religious texts, like Avesta

What I found remarkable wasn't that there are badly managed projects, but that there are software devs who seem to think there is no other way than doing it like that.

Controversial opinion, but in my experience so far people usually say "this is best practice" as a way to avoid thinking, or to masquerade personal preferences. Not always, but more often than not.

As soon as you ask "why is it a best practice?", "what are the consequences of not following this best practice?", "since 'best' implies there's a 'not-best', what is an example of the 'not-best practice' that this wants us to avoid doing?".

The answer is usually something vague and handwavy like "because it's more scalable", but if you challenge that by saying "what do you mean with 'scalable'? can you give an example?", you usually won't get an answer.

Doing stuff without understanding the reason, that's cargo cult.

To be clear, I have nothing against people saying "I understand the code better like this"; it's subjective but honest, and it doesn't try to pass a subjective argument as if it were an objective truth. What I dislike is people saying "this is best practice" like an absolute truth that must be blindly followed and never challenged, without even considering the circumstances of the current project.

Please spare me from turning a simple HTTP CRUD of 4 endpoints into an overkill Icosahedronal Architecture with a reason like "when we need to write an v2 this will make it easier without needing a rewrite!"; because I know that when the time comes for an v2 you'll rewrite from scratch anyway because then you'll want to use the new and better(tm) Perpendicular Riemann Zeta Architecture.

1. Don't use fancy design patterns, FP constructs, performance optimizations etc. Unless the use case specifically requires it.

2. Code should do whatever it needs to do to fulfill its business requirements. Nothing less and preferably also nothing more.

3. Readable code beats documentation: only document the 'why', and only when it is non obvious. If you find you're documenting the 'how', have a second look if you can write your code in such a way that it explains itself.

4. Explain how to build the project, run tests and whatever else is non obvious in a Readme file in your project. Documentation anywhere else, such as on Confluence, will not be maintained or read.