Knowledge Base‎ > ‎Programming‎ > ‎Turing‎ > ‎

Software Practices

Comments

Comments are notes that programmers can add to their code that does not affect the execution of the code in any way. Different symbols are used to denote comments:

  Turing Java and Processing Python
 Single Line % this is a comment // my comment # wow another comment
 Multiple Line  /* a multi line comment
    ....

*/
 """
 this can be considered a comment
 """

New programmers often think of comments as being a waste of time since they  don't actually do anything. In fact good comments are often the mark of an experienced programmer. 

Why Comments - A Scenerio

Imaging you have just started a new job as a programmer and are now responsible for a module that interfaces with some very old code. You start by reading through the various files of code to find that none of the code is commented. To make matters worse much of the code is very obfuscated and difficult to understand. You have a meeting with your supervisor the next day and you are about to raise the issue when you find out you have an important deadline fast approaching and she expects you to updated all of the code with new functionality.

Good Comments

Good comments don't tell programmers they already know. For instance you do need to explain what a for loop is:

// do something ten times
for (n==1; n<=10;n++) {
    moveRobot(n);
}

Instead comments should focus on what a programmer can't figure out from their knowledge or a quick check to the reference manual. What variables mean, what certain conditions represent, why you choose to exit a loop early, what a conditional is checking for, etc.

Comments