Krista's Coding Corner

18.03.2012

Good code? -comments

Comments

Well, some say that really good code doesn’t need comments. That might be true but hardly anyone actually does THAT good code (I hope you do ^^). So, comment your code a lot because after couple of weeks from writing even you won’t remember what the code was for and what it does. And also no one else has absolute no idea… :) Especially comment any parts that are unclear or have some tricks in it. (Preferably: don’t do any tricks!)

Some think that comments are unreliable as the code might change but comments just stay as they were. This is also true: think that you read comment saying “returns 0 if all ok” and the code actually returns “true”. Comments can be wrong because of creators or other developers, but this is more like lack of commenting and is caused by sloppiness. But be aware of the comments ;)

One “warning”: don’t comment things that don’t need commenting. There is no reason to comment “here a variable is created” because anyone should be able to see it. It is way better to tell what variable is going to be for, especially if you have many quite similar ones or if they are parameters of your function. Like: “variable elephant_color is 0 if you have to make blue elephant, and 1 if you have to create pink elephant”.

One could use text “pink" to tell about pink elephant instead of 1 but this makes program more complex and it uses more memory because text pink goes to the processor. Variable names don’t go there and are just for your personal use really, so they don’t use memory. Use long variable and function names but when it comes to their values, think twice what to put in them.

blog comments powered by Disqus