Difference between revisions of "Commenting Objective-C Code"

Revision as of 21:18, 1 February 2016

There is an old saying amongst veteran programmers that goes something like "Don't comment bad code, re-write it!". Before exploring what these seasoned programmers are really saying, it is important to understand what comments are and why we should use them.

Why Comment your Code?

<google>IOSBOX</google> Comments in both programming and scripting languages provide a mechanism for the developer to write notes that are ignored by the compiler or interpreter. These notes are intended solely for either the developer or anyone else who may later need to modify the code. The main purpose of comments, therefore, is to allow the developer to make notes that help anyone who may read the code later to understand issues such as how a particular section of a program works, what a particular method does or what a variable is used to store. Commenting code is considered to be good practice. Rest assured that a section of Objective-C code that seems obvious when you write it will often be confusing when you return to it months, or even years later to modify it. By including explanatory comments alongside the code this becomes less of a problem.

Now, back to that old saying - "Don't comment bad code, re-write it!". What this phrase suggests is that if code is well written in the first place you do not need comments to explain what it does and how it does it. It also suggests that if you are having to write lots of comments to explain what a section of your Objective-C program does then you must have written it badly. Whilst one should always strive to write good code there is absolutely nothing wrong with including comments to explain what the code does. Even a well written program can be difficult to understand if it is solving a difficult problem so, ignore the old programmer's adage and never hesitate to comment your Objective-C code.

Another useful application of comments in Objective-C is to comment out sections of a program. Putting comment markers around sections of code ensures that they are ignored by the compiler during compilation. This can be especially useful when you are debugging a program and want to try out something different, but do not want to have to delete the old code until you have tested that the new code actually works.

Single Line Comments

The mechanism for a single line comment is marked by prefixing the line with // (this will familiar to C++ or Java programmers). For example:

// This is a comment line. It is for human use only and is ignored by the Objective-C compiler.

NSString *myString;
int i = 0;

// This is another comment

The // syntax tells the compiler that everything on the same line following on from the // is a comment and should be ignored. This means that anything on the line before the // comment marker is not ignored. The advantage of this is that it enables comments to be placed at the end of a line of code. For example:

NSString *myString = @"Welcome to Techotopia"; // Variable containing pointer to welcome string object

In the above example everything after the // marker is considered a comment and, therefore, ignored by the Objective-C compiler. This provides an ideal method for placing comments on the same line of code that describe what that particular line of code does.

Multi-line Comments

For the purposes of supporting comments that extend over multiple lines Objective-C borrowed some syntax from the C programming language. The start and end of lines of comments are marked by the /* and */ markers respectively. Everything immediately after the /* and before the */ is considered to be a comment, regardless of where the markers appear on a line. For example:

/*
This Function adds two numbers together
and returns the result of the addition
*/

(int) addNums (num1, num2)
{
return (num1 + num2)
}

Multi-line comments are particularly useful for commenting out sections of a program you no longer wish to run but do not yet wish to delete, together with an explanation of when and why you have commented it out:

/*

Commented out December 23 while testing improved version

int myValue = 1;

NSString *myString = @"My lucky number is ";

NSLog ( @"%@ %@", myString, myValue );

*/

Summary

Comments in Objective-C enable the developer to add notes about the code or comment out sections of code that should not be compiled. Comments can be single line comments (using the // marker) or multi-line (beginning with /* and ending with */).

Commenting is considered to be good practice. Regardless of how well you understand the logic of some Objective-C, there is a good chance you may one day have to return to that code and modify it. Often this can be months, or even years later and what seemed obvious to you at the time you wrote it may seem less obvious in the future. Also, it is often likely that some other person will have to work on your code in the future. For both these reasons it is a good idea to provide at least some basic amount of commenting in your code.