How To Improve Code in Unity Using Comments

Of course, you probably know about comments and that they don’t do anything anything inside your code. So what’s the point of them? How can comments help improve code in Unity?

Comments help improving your code by providing it with documentation and context. Yet, there are some important pitfalls that should not be overlooked. In this article, we will discuss some of these pitfalls and lay out some best practices.

Why Comments Are Important in Programming

As mentioned before, comments improve your code by adding extra context to it. Every time you add a comment, you add information about what the code does. As a result, you are documenting your code. which is important because software projects can get really complex with thousands of classes and millions of functions. Yet, documentation should not solely consist out of comments.

How Much Should You Comment Your Code

While adding extra documentation about your code through comments is fine, you should never try to overdo it. As a general rule, you should strive for writing self documenting code that does not need any type of comments. With self documenting code, it’s not necessary to document every single method or class inside your project. You should focus on commenting the classes and methods that are most frequently used or the most complex.

However, if you are working in a team, there probably is some kind of a coding standard. This standard dictates the way the code should be written and what documentation standards it should adhere. While some standards are incredibly strict regarding comments, others tend to be rather relaxed. Next, there are also companies that don’t allow any comments in their software at all. Usually, these companies refer to their tests as a way to document the code. As you can see, there is no general agreement on how much you should comment your code.

Examples of Bad Commenting in Unity

The following examples demonstrate several cases of bad commenting practices in Unity. Again, since there is no golden standard, you should use the following examples as guidelines. The are code standards out there that would disagree with some of these practices.

Why Ambiguity in Comments is Bad

When commenting your code, it is important not to state the obvious. As a result, it often looks like you’re commenting just for the sake of commenting. It’s not productive at all since no new information is being listed about the code. Below you can find an example of ambiguity in comments. In this example, the comments state the obvious. Even without reading the comments we can figure out that this is the HealthPickup class and that it inherits from a MonoBehaviour. There is no need to add this information through comments.

using UnityEngine;
 
/*
  The Health Pickup Class. Inherits from MonoBehaviour
*/
public class HealthPickup : MonoBehaviour
{
    ...
}

Why Oversimplification in Comments is Bad

Another bad practice is to oversimplify your comments too much. In the snippet below, there is a comment describing that we can use the Shoot method to shoot a bullet. However, does this give you enough information? What if the game features both a normal and a homing bullet? Do we still need to specify the target if the bullet isn’t homing? Clearly, it’s important to provide enough details in your comments.

using UnityEngine;
 
public class Player : MonoBehaviour
{
    // Shoots a bullet 
    public void Shoot(GameObject target, GameObject bullet, bool reflective = false)
    {
        ...
    }
}

Why Legacy Code In Comments is Bad

Finally, you should avoid at all costs to ‘ disable’ legacy code through comments. In this scenario, we have commented out a previous implementation of a method that does raycasts. There is no good reason for the old implementation to still be in the method next to the new implementation. Actually, it is often a fear of losing the old implementation that leads to code like this.

using UnityEngine;
 
public class Enemy : MonoBehaviour
{
    private void Update()
    {
        // Old Unity implementation, leave this here for now.
        /*
        bool canSeePlayer = Physics.Raycast(transform.position, transform.forward);
        */
 
        bool canSeePlayer = XPhysics.Ray(transform.position, transform.forward);
    }
}

Best Practices for Comments in Unity

Now that we know how you can improve your code in Unity using comments, we would like to mention some best practices:

• You should focus on commenting the classes and methods that are most frequently used or the most complex.
• Don’t forget to update the surrounding comments if the code changes.
• In case of a method, clearly explain what the method does and what inputs it expects. If there is a similar method, clearly explain what both methods do differently.
• In case of a class, clearly outline the main purpose of class.
• Try to avoid writing comments by writing self documenting code. The best comment is no comment.

Summary

What you learned in this article:

• Comments help improving your code by providing it with documentation and context.
• Documentation should not solely consist out of comments.
• You should strive for writing self documenting code that does not need any type of comments.
• You should focus on commenting the classes and methods that are most frequently used or the most complex.
• There is no general agreement on how much you should comment your code.
• When commenting your code, it is important not to state the obvious.
• it’s important to provide enough details in your comments.
• Avoid at all costs to ‘disable’. legacy code through comments.

Conclusion

To end, we hope you now have a better understanding of how we can use comments to improve our code in Unity. In this article we discussed how it’s better to focus commenting on important elements rather than commenting too much. In addition, we have shown several bad practices of comments that you can use as general guidelines. Ideally, you should strive to write self documenting code that will eliminate the need for comments even further. Simply put, the best comment is no comment.

Further Reading

Other articles you may find interesting:

• How to Improve Code in Unity Using SerializeField
• How To Improve Code in Unity by Using Enums
• Writing Self Documenting Code