Be understood, not clever

This title is inspired in a section of a Book called "Clean Code in PHP" by Carsten Windler, and Alexandre Daubois, which I recommend you to read if you're into PHP and somewhat new to clean code practices.

This might be a silly piece of advice, but I constantly find myself trying to understand what past-me wrote in some projects, although, I don't blame past-Tony, a few years have passed by and I'm a different developer now. In recent years I've been adopting a more verbose approach when it comes to code overall (both in code and in my commits).

Let me be clear

You should not solely rely on comments when writing code, but instead, using a mix of descriptive variables, methods, class naming and, of course, comments. You see, something that may be obvious to you now might not be as clear to your 6-months-in-the-future self or your teammates.

If you want some thoughts on naming and codebase structurization I'd suggest you to watch this 2017 Youtube video from Adam Wathan (yes, the good guy from Tailwind used to talk about PHP back in the day, I've been around so long I can remember that).

Let me give you an example from a recent TypeScript adventure:

// Remove diacritics, i.e. "ame\u0301lie.com" or "amélie.com" will lastly be "amelie.com" 
let sanitizedString: string = Diacritics.remove(domain.toLowerCase());

sanitizedString = sanitizedString.replace(/^www\./g, '');
sanitizedString = sanitizedString.replace(/[^a-z0-9-.]/g, '-');

^{In this snippet, we're sanitizing a domain string from an input by replacing diacritics, stripping "www." from the beginning if it's present, and finally removing any non-alphanumeric/dash/dot characters and replacing them with dashes.}

Imagine if you were to revisit this code months later or if someone else had to maintain it, and you don't make that comment in the starting line. Future me could forget Diacritics' remove method does not mean to remove characters with diacritics but to replace them with the most close diacritic-less characters.

And... finally...

TypeScript ends up wiping all of those comments when it does transpilation to JavaScript code, so don't be afraid to spare a few lines on your source code helping your future self.

PHP and other languages have mechanisms to avoid performance hits while parsing files (ignoring comments, whitespace, etc). I'm not in the position to say all languages/tools won't take a hit on being verbose in your comments, but most languages I know ensure you can feel safe to use as many comments as you like.

Happy coding!