I have always liked code that explains itself.
Not literally, obviously. I mean code where you don't have to spend five minutes figuring out what the author had in mind.
I like functions with names that tell you what they do.
ProcessData() doesn't tell me much.
BuildPlayerInventory() does.
It is a tiny thing, but it gives your brain a shortcut. You see the name and you already know what you are about to get into.
I feel the same way about variables.
I don't really like generic names such as data, value, object, manager, result etc. when there is a more specific name available.
And there is a very practical reason for that, especially when working with something as big as Unreal Engine.
Imagine you are writing a small function. You need a temporary variable, so you call it value.
There is absolutely nothing wrong with that variable within the context of your function. The code makes perfect sense.
Until you compile it.
And suddenly you discover that the name you picked happens to collide with something used by the engine.
The funny thing is that you didn't do anything particularly wrong.
You were thinking about your little function.
Unreal has to think about the entire engine.
This is one of the reasons I like contextual names. They make the code easier for another human to understand, but they also reduce the chance of accidentally stepping outside of the context you had in your head when you wrote the code.
Comments
And then there are comments.
I know a lot of people who don't like comments.
The argument usually goes something like:
"If the code is good, you should be able to read it and understand what it does. Why add comments?"
Well...
Because comments don't compile.
They are not there for the compiler.
They are there for us.
A comment can explain a concept. It can explain why something is done in a particular way. It can tell you that something is deliberately implemented this way for now. It can point out a limitation, a known problem, or simply give you a little shortcut when you come back to the code six months later.
Of course, comments need to be maintained.
A wrong comment is probably worse than no comment.
But that doesn't mean comments are bad. It means we need to treat them as part of the codebase and keep them relevant.
The ironic part
And here comes the slightly ironic part.
I've been using AI quite a lot for writing code lately, and one thing I noticed is that AI is actually pretty good at this.
It tends to come up with descriptive function names.
It tends to give variables names that make sense in the context where they are used.
And when it adds comments, they are often there to explain the "why", rather than simply repeating what the code is already saying.
So maybe we should learn from it.
We spend a lot of time teaching AI how to write better code.
Maybe we should also pay attention to the things it already does well.
Self-descriptive code is a good thing.
For AI.
And, surprisingly, for humans too.