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

Comments

[Phil Ashby]

This is also known as the pseudocode approach, which has good and bad points, as @danrot90 brought up here: dev.to/danrot90/code-comments-are-... =)

There is a similar but possibly more helpful approach (that I am unable to find my original reference for sadly - too long ago!) whereby you assume dependent objects have the methods you need to write a complete piece of logic, so you concentrate on the one thing, then go back and fill out the dependencies later (the compiler will nicely tell you what's missing!) - avoiding getting lost in the wormhole of implementation detail. I use this a lot :)

[Christian Gröber]

Yeah I guess that's a very valid argument. But I don't think my approach really repeats what the code does, it summarizes what a code Block is supposed to do, so if we look at the example from my post and I decide I want to change how the name of the file is determined. Now I can tell, just by looking at the comments, that that will have to be in the first code block.