Good Programming Comments

Writing good programming comments can be crucial to cooperation among programmers. Ideally variables and functions would be well named, but naming conventions are not perfect. Furthermore, code can become difficult to read pretty quickly. A lot of algorithms can be abstract, and you cannot control how built-in functions are named. They can also help when you come back to your code several months later and need to remember what you were doing. Now, that being said some people do not like comments because they believe it leads to ‘lazy programming’. I think the best middle ground is only commenting on abstract functions that cannot be simplified.

A good comment has three components: parameters/arguments, return values, and a description of its purpose. In this case a parameter and argument is typically synonymous, and is basically the value you want the function to consider throughout its operation. Whereas, on the flip side the return value is the value you get out of the function when it is complete. Typically it is good practice to include a data type with this information, but that’s not always necessary. Lastly, if an algorithm is abstract it makes sense to break it down if possible in English.

Leave a comment

Your email address will not be published. Required fields are marked *