On the journey to writing better comments

Tl;dr: Write them before writing the actual code

You always hear how you should write more, better comments... But this is a habit we probably all struggle with

A few days ago I was working on a function that I knew what it should do, which is to take an image at a specified path and create a copy of that image with a different width to a subfolder of the original image, the subfolder's name being the new width.

Here is the base structure of this function (yes, I write PHP, sue me):

    public function compressImage(string $imagePath, int $size)
    {

    }

I knew what the function should do, but didn't quite know how to make it do what I wanted to, so I jotted down my ideas in the form of comments:

    public function compressImage(string $imagePath, int $size)
    {
        // Find out path of original image
        // Scale down image
        // Create new path if it does not exist yet
        // Save scaled down version in new path
        // Return relative path to compressed Image
    }

With this I managed to organize my mind. Next came the part of actually writing the code, which was now a lot easier because the comments told me, what I was supposed to do. This is the final function:

    public function compressImage(string $imagePath, int $size)
    {
        // Find out path of original image
        $originalImgPath = '';
        $splImgPath = explode('/', $imagePath);
        $fileName = array_pop($splImgPath);
        $originalImgPath = implode('/', $splImgPath);

        // Scale down image
        $imgObject = imagecreatefromstring(file_get_contents($imagePath));
        $scaled = imagescale($imgObject, $size);

        // Create new path if it does not exist yet
        if (!is_dir("${originalImgPath}/${size}")) {
            mkdir("${originalImgPath}/${size}", 0777, true);
        }

        // Save scaled down version in new path
        imagejpeg($scaled, "${originalImgPath}/${size}/${fileName}");

        return "${originalImgPath}/${size}/${fileName}";
    }

(I was lucky because I could basically just copy the part of the actual scaling (imagejpeg($scaled, "${originalImgPath}/${size}/${fileName}"); from a function I'd written a few months ago, so it was pretty much straight-forward.)

I hope you found this approach interesting and will be able to at least give it a try in one of your own projects. I would also be delighted to hear your ideas on how to write good comments.

Lastly, I hope you have a lovely day, wherever you may be