The PHP Project Guide (2014)

11. Commenting code

Commenting code is an extremely underutilised practice. Why? Because more often than not a programmer will assume that down the line, they’ll know exactly what the code is, what it does and how to change the code if required. This is absolutely natural, however many of us have become victim to opening a file full of code that we wrote days, months or perhaps years ago, only to find that we have a much harder time understanding it than we anticipated.

If you’ve ever opened up someone’s code and not understood it as a whole, but know deep down that you understand the fundamental parts that make it up, then this is exactly what you’ll encounter when you open up some uncommented code of your own.

Recommending that programmers comment their code isn’t enough, because a comment could be anything. When we’re talking about commenting, we’re not talking a little note here and there, we mean a full explanation of what something does, why it does it, how it does it and what could be improved if required. Of course, this extent of commenting would be silly for a line that simply output some contents, but if these contents were contained within a variable for example, it would still make sense to make a quick note of what it’s actually outputting. This would make it much easier to scroll down the application, see this output building up and then quickly being able to spot where it’s being output.

Commenting helps the author understand their own work when it’s reviewed at a later date, but also for other developers. As we’ve already mentioned, other people may join a project at a later date, and commenting makes it a lot easier for someone to quickly scan an application and gain a good understanding of the code and what each part does in relation to the code as a whole. This of course depends on knowledge of the language, but you’ll be surprised that giving a well commented file to someone learning a programming language can actually really help teach it.

Another good reason to comment brings us to the very top of a file’s code, the meta information about a file. This can be very useful to display meta data such as when the file was created and modified, the author of the file and a brief overall description of what the file does. You may also see information here about how the file can be used. For most of this meta information, a text editor can be set up to automatically insert or update this information. So, every time you save a file, the note to say when the file was last updated could be automatically changed.

So, why is it important to include author information and the date of creation or modification? With regards to the author information, it makes it a lot easier to get help with the file within a team if you know who created the file. In open source software, you may need to contact the author with important information, such as a discovered bug, security flaw or recommendations. Put simply, the date will tell someone how old the file is, which could be used to flag any files that may need to be reviewed for deprecated functions. Functions or methods will have been deprecated for good reason, so reviewing old files will mean that an application can be kept up to date easily.