Complicated code is not clever

I remember when I first started learning to code, I would be reading snippets online would find myself having to read things over and over again to be able to understand them.

The problem wasn't with the logic of the code or with what it was doing, it was how it was written.

Consider the below PHP code snippets, which do you think is more readable?

function json($arr){echo json_encode($arr); die();};

$a = array('t'=>time(),'un'=>$ufn.' '.$uln,'tn'=>utn($ui));

json($a);

function outputArrayAsJson(array $array)
{
    echo json_encode($array);
    die();
};

$response = [
    'time' => time(),
    'userName' => $user->firstName . ' ' . $user->lastName,
    'teamName' => getUserTeamName($user->id)
];

outputArrayAsJson($response);

This is obviously subjective, but I think generally more people (developer and not) would be able to understand the latter solution over the former.

Using the above examples which are written in PHP just scanning over the code of each you can quickly understand what is happening in the second snippet much faster than the first.

You're unlikely to need to go searching through your codebase to find what getUserTeamName($user->id) does, its name and arguments are already indicative of its use case. However compare this with utn($ui) which is not so clear. I can guarantee that if you left this codebase for any period of time you would need to go back to the utn function to remind yourself what it does.

There are going to be things referenced in any language which are outside of our control, such as bundled standard libraries, but the things which we do have control over should be produced to as high a standard as possible.

I believe that code should generally read like a story or a book. If you had to constantly keep flicking between random pages of a story would you be likely to finish the book? Almost certainly not. As developers it's important to not only write efficient, but also, understandable code. Doing so reduces technical debt and makes the development experience far more enjoyable.

You don't need to be an expert to write clever code.

Here are my top tips for writing clever code:

Conventions

Pick one and stick to it. There is no right or wrong, tabs or spaces, camel-case or snake-case, it doesn't matter - just create a convention stick with it. Consistency is the key.

Whitespace

Bunching up concatenations or blocks makes them harder to read. Similarly keeping short statements on one line, and splitting longer statements into multiple lines makes them easier to follow without needing to scroll.

// These are bad
$variable=$a+$b;
if($variable===101){
return rand(1,5)+2;
};
functionWithLotsOfParameters(true,[1,2,3,4,5],$ui,null,MyObject::class);

// These are good
$variable = $a . $b;

if($variable === 101)
{
    return rand(1, 5) + 2;
};

functionWithLotsOfParameters(
    true,
    [
        1,
        2,
        3,
        4,
        5
    ],
    $ui,
    null,
    MyObject::class
);

Descriptive Names

Make your code the comment. All names which you have control over as a developer should be descriptive. A function called outputArrayAsJson(array $array) tells the developer exactly what it does without even needing to read the logic inside the function. You are never going to remember exactly what your code does when you revisit it in a year, so make the code readable.

Comments

Comments should explain why you needed to do something, but not how. Code changes often, but comments are commonly missed when the logic changes. I've lost count the number of times where I've copy/pasted code between 2 files and forgotten to update the comment context.

Scopes

Make use of scopes where possible and try to group common logic together. Grouping portions of similar code together, such as in a class, makes things much more maintainable and avoids code repetition. Only use global scopes as an absolute last resort.

// This is OK
http_response_code(404);
die('Page not found');

// This is better
class Response
{
    public const HTTP_NOT_FOUND = 404;
    public const HTTP_NOT_FOUND_MESSAGE = 'Page not found';
};

http_response_code(Response::HTTP_NOT_FOUND);

die(Response::HTTP_NOT_FOUND_MESSAGE);