Commenting your custom functions

Writing a lot of custom functions on your website can be great as it unlocks lots of extra functionality.

However trying to remember:

• When a function was written
• Who it was written by (if working in a team)
• What the function does

can sometimes be a challenge.

That is why I created a snippet that I insert just before each function I write for my future self.

Example

        <?php

/*
 * tct_hello_user
 *
 * @function Returns greeting to user based on time of day
 * @author Taylor Drayson
 * @since 25/09/2022
*/

function tct_hello_user(){
    if (is_user_logged_in()) {
        $morning = ['morning matey', 'Top of the morning'];

        $afternoon = ['Afternoon', 'How was lunch'];

        $evening = ['You should be asleep', 'Sleep well'];

        $hour = date('H');
        $username = wp_get_current_user()->user_login;

        if ($hour < 12) {
            $random = array_rand($morning);
            return $morning[$random] . ' ' . $username;
        } elseif ($hour > 11 && $hour < 18) {
            $random = array_rand($afternoon);
            return $afternoon[$random] . ' ' . $username;
        } elseif ($hour > 17) {
            $random = array_rand($evening);
            return $evening[$random] . ' ' . $username;
        }
    }
}
      
Copy

As you can see in the example above:

• The first line is the function name
• The @function line describes what the function does
• The @author line tells you who wrote the code
• The @since line tells you when the function was first written

This is by no means the best or most elegant method, but it works for me and has helped me in the past when coming back to code.

How I use it

I use Alfred snippets which allow me to quickly paste the function prefix wherever I need it. I have it set the author to Taylor Drayson by default as its my computer. Plus I use a dynamic placeholder to automatically populate the current date.

This could be slightly modified to work with your own text or snippet expander.