Magento Dev Best Practices: Code Commenting

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
This entry was posted in Best Practices, Magento. Bookmark the permalink.

3 Responses to Magento Dev Best Practices: Code Commenting

  1. I agree that every file, class and method should have a comment block. However, I don’t agree that there should be many comments within (except variable comments pointing out their class which are absolutely useful). If you need many comments to make your code understandable, the naming of your methods and variables isn’t clear enough and/or your methods are too long. Of course, in some cases it’s necessary, especially when dealing with APIs.

    • Josh Pratt says:

      Andreas – I agree that commenting completely obvious things is not necessary. But, you also need to recognize that what may be obvious to you may not be obvious to other developers to use/inherit your code. It’s always WAY easier for the original developer to understand your own code than for others to understand your code. It can be risky to assume what is obvious and what is not, especially in the programming world these days.

  2. Pingback: Mejores practicas para desarrollo de extensiones en Magento @MagentoExtensiones