This is the second post in a series about Magento development best practices, and it is about code commenting. High up on the top list of shortcuts developers take is failing to properly comment code. And, the excuse, nearly every time, has something to do with being under a deadline and not having time.
You may save a couple minutes here and there, but ultimately you may cause many more minutes, hours, or even days by not properly commenting your code. I believe it should be the habit of every developer to make your file comment right when you create your file, make your class comment right when create a class, make your function comment right when you make a function, and comment about functionality within as you go. If you do it as you go, you won’t forget to do it later, and you won’t forget about what functionality might be doing. You’ll never have to spend the painful time to go throughout your entire module you just wrote and comment everything.
Properly commented code has the following benefits (and plenty more):
- Makes it easy for you to understand/remember what your code is doing should you need to modify it later
- Makes it easy for someone else to understand what your code is doing if they need to modify it
- Looks great and shows professionalism
- If you do it using a standard like PHPDoc, you can easily make documentation automatically from your code
- Assists in IDE code completion
The standards I follow for myself and I encourage teams that I am a part of do do as well in terms of Magento module development:
- Commend EVERY file, even if it’s an xml file, template file, etc. Every file has my modules file doc block at the top. Very important is the @author tag so we know who’s worked on the file
- Every class has a doc block title and description if necessary
- Every function has a doc block describing what it does
- Within functions, template files, etc., there are many comments explaining what is going on and why certain things are happening to make it very clear and understandable