A Few Comments On Commenting Code Practise.
Like our development team, you may find yourself asking the question “What code should I comment?”
Here are a few of the benefits we have found from having a comments practice in place, and the downside to not commenting.
“Will you know what your code is doing in six months?”
...or will anyone else for that matter? As developers, our coding style changes with experience. To demonstrate, take a look at another developer’s code or one of your own past projects. It’s pretty safe to say that you think you know what's going on, although you’re not 100% sure.
“If you can’t work it out, then you shouldn't be a developer”
Yes, that has been said to me before. Not only does it highlight a lack of commentsense (sorry, I had to get that in here somehow), but a misunderstanding of commenting altogether. So I’ll explain.
Comments shouldn't be used as descriptions for each variable assignment or function call, but more for the logic process that is happening inside a script, method or function. It’s not always what a piece of code is doing, but the wider reason you've chosen to do it that way which you (or someone else fresh to it) will need reminding/explaining in 6 months.
Consider this: you have a file that contains functions or object declarations; you add a description above the function detailing what is about to happen, if you have a process inside that function that’s outside the “normal” then give it a little comment.
It could take you twenty minutes to read through uncommented code, jumping between classes, functions and files or sixty seconds to read a comment segment.
“What help can I get?”
There is a standardisation out there to get you on the straight and narrow, take a look at www.phpdoc.org. PHPDocumentor will fully explain how to accurately and efficiently comment you code. After a ten minute read you might be thinking that it’s excessive, but if you install some PHP Intellisense plugins into your IDE, such as Sublime’s CodeIntel, Atom, or Eclipse, then you will pick up class and function description, and pre-populate your code with default function variables.
Some Key Things To Remember:
- There is a difference between commenting your code and documenting it. Use your comments to highlight breaks in logic or as an explanation to a process.
- If you take commenting your code to the ‘nth’ degree, then your project would suffer from a serious case of #blotting.
- Document your code to the PHP Documentation standard to improve method intellisense.
- Golden Rule: if you think it needs commenting, then it does.