Nobody gives a straight answer when asked “how do you make good comments?” The responses are all formatted in terms of what to do and what not to do. Don’t overdo it. Don’t try to make them look pretty. Be concise. The vague-ness of our answers exists because there’s no right way to comment, but there are plenty of wrong ones. Also, strong-arming a particular cookie-cutter series of required components can potentially lead to bloated, irrelevant comments. Even so, as an industry with so many existing development and production standards and so many different coding styles, why is there no standard practice for commenting? Would this not vastly improve the quality and readability of our collective code?
When it comes to Unity, the entity-component system that the engine employs makes so much damn sense, it’s a wonder that not all development platforms follow a similar system. When so many games depend on interacting elements in 3D space nowadays, simplicity and flexibility are at the top of the list in terms of organizing assets and code.
It is because of this system, why not do this…
/* MobileControls
* Attaches to: Player
* Function: Controls device touch points, rotates and translates the character
* Function: Displays the directional pointers */
Okay fine, given that the functionality of this particular MonoBehavior isn’t very complex, we allow for simplicity in the comment. However, the way the Unity Engine is set up, the ability to create ambiguously floating scripts often lends itself to require answers for two questions: where do I go, and what do I do? Answer them, and for the most part, you’re golden.