Hey there 👋 I'm back with another little rant!
The other day I was thinking about what makes good code good. Or better said, the variables that make it good. Good for me that is.
For me the variables of good code are: Planning, Skill, Consistency, Iterations/Refactor, Observing and most importantly Caring. Or PSICCO for short, as I know the industry loves a good acronym. It's not as good as KISS but whatever 🤣
So let's go through them and give a bit more context!
Planning
After thinking for a while I've come to the conclusion that one of the most important, or at least the first thing we must do to be able to create good code is to plan.
Days of coding can save you hours of planning...
This sentence is funny because it's not true. Planning can save you hours of coding. Or at least hours of coding shit, it's not ensured you won't, but it can help.
Consistency
Consistent code is predictable and requires less effort to navigate and understand.
Take this example, your project has a lot of entities and mocks, and tests for those entities. Let's see the difference and then you can interpret it as you like.
Inconsistent
We have these entities:
- user.entity.ts
- account_entity.ts
- book.ts
These are the mocks:
- mock_user.entity.ts
- account_mock_entity.ts
- book_mock.ts
tests:
- user.entity.test.ts
- account_entity_test.ts
- test_book.ts
Of course, this example is very exaggerated, but you'd be surprised.
You can imagine navigating or trying to deduce how a file's name can be extremely complicated if possible. At least it's not very efficient, as you would need to check how each file is named.
Consistent
- user.entity.ts
- account.entity.ts
- book.entity.ts
These are the mocks:
- user.entity.mock.ts
- account.entity.mock.ts
- book.entity.mock.ts
tests:
- user.entity.test.ts
- account.entity.test.ts
- book.entity.test.ts
Now, being consistent you can easily predict how a mock or test file for a certain entity will be named. If you want to import the mock for a book, just add .mock to the end of the entity file name, and so on.
We, humans, have evolved to learn patterns very well, and being consistent in code is all about following patterns. This of course is very valuable as we can very easily learn them and predict stuff we don't yet know.
Meanwhile, with inconsistent code, we cannot.
As a side story, I recently started working with discourse and its plugin environment. After having a quick look at some plugins and examples I could almost instantly understand the patterns and find all the classes, variables and files I needed just by assuming they would follow the same patterns. They did, and that was incredibly satisfying and made me keep working with it. It does not only help the current developers or contributors but also makes people more comfortable to start contributing and helping out.
Iterations
Or better known as refactoring is one of the best tools at our disposal to continuously improve our code every single day. I really think it's one very powerful tool and even wrote a post talking just about that. Here it is in case you want to have a read!
In short, by iterating and continuously improving our code, with reason and thought, of course, we can make our code a lot better than it once was. No code is perfect from the start.
Observation
Observe how your code is being used, how you use it, what problems it gives you, what it does well, etc... Just observe and analyse it often, this will give you clues on what to work on next, what to improve or what to not touch.
Skill
This is of course one of the most important points, without it, no matter what, you will not be able to create great code. In the same way, a pianist will not play extremely complex melodies without the skill and basics. Or an athlete will not be able to be the best at 100m without skill and practice.
Caring
Apart from skill, I feel like Caring is the most important aspect for good code.
I think that good code is done by people who care about the code and project they're working on. They take the time to do things well, they are consistent, in the same way that good handmade jewellery or furniture is done by people who care about the product they're making.
Now, what are your thought?
Have I missed some important points? And are there any other points/variables you would say are also important for creating great code?
Top comments (11)
Great post! The "iteration" and "observation" point really stuck out to me mostly because I think code is means to an end - to serve our end users and the business. It's important to not get bogged down towards making it perfect from the get go, or to stick to your metaphor, in trying to create a masterpiece with every program or code fragment you write
Thanks!
Yup, you should do it the best you can at a given moment, and continuously analyze and improve it. Masterpieces take time and effort
I feel triggered because that a variant of this is in my bio :)
But that's precisely what the quote says!
Only that it says it ironically to poke fun of the "planning is overrated" people.
Hahahahah I know it's a joke, just modified it a bit to better fit the post... Hope it did not trigger you too much xD
Regarding your (good !) point on consistency, in my case I would put it under "refactoring", because I'm just unable to start with something consistent and coherent first.
So
Not a bad point at all. I separated them because I feel we must think of consistency on it's own and refactoring encapsulated a lot more than just this. But I agree, first make it work, then make it good. But, if you can make it decent from early on, it will be easier to do so.
Good post. My snarky one liner is as follows:
I do care about my code like an artist cares about their painting, but that doesn't mean anyone else cares about it.
Good way of looking at it!
But artists are paid after the thing is done, we're paid to solve problems with help of computers... How to find a balance?
I'd say it's mostly the same, only the medium changes. I would even say that it's more important for us to take care of our code bases as we will be working on them for a long time.
Eu vejo o Código como um livro que escrevo. Cada detalhe do mundo que escolhi influenciar ou resolver um problema deve ser simplificado claramente em código.