Code Clarity

How good practices around your code can improve your workflow.

I want to share some of the conventions I try to follow in my projects, and why I use them in this way.

Introduction

These are some practices that improve oversight and collaboration in projects for me. This is not about code style itself: there are a lot of books out there about that, written by way smarter people than me; but rather about everything interacting with the code itself. Some of this article is related to the programming languages I use most often at the moment, which are PHP and JavaScript/TypeScript, but I try to keep it as general as possible.

Conventional Commits

Conventional Commits have fortunately become the standard for many open-source projects, and I fully embrace it. They suggest a clear, short commit message that indicates the scope of the change (fix:, feat: chore:, etc.), which can be useful for a number of reasons:

1. Reviewers see immediately what changes they should look out for when reading the diff just by looking at the commit message.
2. It encourages smaller commits: different concerns should be split into multiple commits in order to follow Conventional Commits. This also improves readability for code review.
3. Changelogs: Tools like changelogen can use the commit message structure provided by Conventional Commits to automatically generate a Changelog.

Signed Commits

While this might not be entirely matching the theme of this article, I want to mention it anyway when writing on the topic of commits, because I think it's important.

I always wanted to do signed commits, and it took me some time to initially set up on my Mac and have it synced with Keychain, but I think it's totally worth the effort.

When I see the green verified badge attached to someone's commit on GitHub, my mind immediately interprets this as a sign of quality.

But just like with SSL and every other cryptographic certificate, this only ensures authenticity of the source, and not more. Of course everyone, even malicious actors, can verify their commits. So this doesn't replace a required level of trust in the source itself.

Comments

When it comes to code comments, I mostly try to keep it concise. If something needs a lengthy explanation, the implementation isn't that good to begin with.

Comments should always serve a purpose. They should explain the why and not the what. If you structure your code well, the what should be clear from the code itself. But that only applies to self-contained code and not the whole project. User-facing code from e.g. a library or framework should explicitly document the what.

For that use case, doc blocks are a great way to document the what and how of a function or class. I try to keep them concise, but not missing any important information.

/**
* Parse, process and save the file.
*
* @param string $path The absolute path to the file.
*/
public function processFile(string $path): void
{
  // Implementation
}

Another exception to that rule is when a comment's purpose is to be documentation, like a Laravel configuration file. While I don't quite craft my comments into such an explicit form as Taylor Otwell does, I like to approximate his style.

Here's an example of his out of Laravel's default app configuration file:

/*
|--------------------------------------------------------------------------
| Application Name
|--------------------------------------------------------------------------
|
| This value is the name of your application, which will be used when the
| framework needs to place the application's name in a notification or
| other UI elements where an application name needs to be displayed.
|
*/

I find this to be a pure joy to read, but only applicable in the right context.

Dead Code

I guess this should be common practice by now, but I've been guilty myself in the past and still see it way too often: Don't comment out code. Just delete it.

Commented out code is a sign of laziness and lack of confidence in your own decisions. It shows that you don't trust your own judgement and are afraid to make mistakes. Dead code just makes things unreadable, and add unnecessary noise to the codebase.

Some common arguments I hear against this strict approach:

"But I wanna know what was there before"

Use the Git history.

"But I wanna know who changed it"

Use Git blame.

"But I want to know why it was deleted"

Use conventional commits and look at the commit message.

"But I want to test things out and maybe revert it"

Use a different branch for that.

In short, if you need to comment out code, you're using Git wrong.