How to make a codebase readable ?

Plenty of time goes into creating a neat looking file structure for your next big project. There are multiple tools like linter, prettier and static analyzers that make sure the code you and your contributors are writing is following a common style guide. Most PR review comments go into the nitty-gritty of code structure rather than logic. and one of the hardest problems a developer faces is naming a variable. All this to make sure that the code is readable !

Following certain guidelines ensures that the code remains readable for both new and existing contributors. Without these guidelines, code can become illegible within weeks - yes, I said weeks. Before long, someone will suggest refactoring perfectly working code to make it more elegant, only to throw it away a few months later.

Documentation and code comments are helpful, but when the help document for a routine like getSum simply says “get the sum,” it doesn’t provide much useful information. The only way to find out what’s actually happening is to ask questions during discussions, which often happen in emails, Slack, Discord, or GitHub comments. All the knowledge is distributed across multiple platforms, making it difficult to access when you actually need it - like when you’re working on a feature and trying to read code that you wrote yourself a few weeks ago, and in fact explained it to a colleague over a water break. But now you can’t recall why the hell you wrote it that way…

I’m not trying to make a point, but just pondering: How can we make code more readable?