AndyBargh.com

Exploring the World of Swift and iOS Development

You are here: Home / Objective-C / Objective-C Code Comments

Objective-C Code Comments

posted on

Picture of tin with Comments written on it

In computer programming, code comments are annotations that you can add to that help with improving the readability of your source code and also help other programmers understand what you were trying to achieve when you were writing it.  In this post, we’re going to take a quick look at how you can add code comments to your own Objective-C code.

In a similar fashion to white space, comments are completely ignored by the compiler and linker when you build your application (if you can’t remember what the compiler and linker do go back and read my post on ‘The Four Phases of Implementing an Objective-C Application‘) and in Objective-C there are two types comments that you can use in your code: in-line comments and block comments.

In-line Comments

Inline comments start with a // (double forward-slash).

With inline comments all characters after the // up to and including the end of the line are ignored when you build your source code.  An example of this is shown below:

// This is an example of an inline comment.

You don’t have to put the // at the start of the line either.  It’s perfectly valid to have a single line in your source file with code statements at the start of the line (Objective-C reserved words and the like), have a // and then have rest of the line dedicated to a comment.  Maybe something like this:

NSLog(@"hello") // a mixed line of code and comments

Just remember that everything after the // will be ignored when you build your program.  Syntax highlighting should point you in the right direction.

Block Comments

The second type of comments in Objective-C are called block comments.

Block comments differ from inline comments in that they start with two characters a /* (forward slash followed by a asterisk symbol) and end with a */ (a asterisk followed by a forward slash).  As an example, take a look at the line below.  It shows an example of using a block comment on a single line:

/* This is a block comment on a single line. */

Now, although block comments can be used on a single line, block comments differ from in-line comments in that they can also span multiple lines (i.e the start symbols on one line and the end symbols on a different line).  All text between the start and end symbols are part of the comment and as with inline comments are ignored when you build your source code.  An example of a block comment that spans multiple lines is shown below:

/*
    main.m   
    HelloWorld
    Created by Andy Bargh on 30/03/2013.   
    Copyright (c) 2013 Andy Bargh. All rights reserved.
*/

Comment Best Practices

Now when it comes to writing comments there are a few things you need to remember.  Think of these as best practices, rules and lessons that the programmers who have come before you have learnt (often painfully):

  • Comments are added to your code to help explain your intentions when you were writing it.  As such, remember to write your comments for humans rather than for a computer.

  • It’s easier to write comments as you go along.  I can’t think of any programmers who actually like writing comments and it’s a lot easier to do so when you have just written the source code and it is fresh in your mind than it is to retrospectively go back and work out what you were trying to achieve.  Trust me, we all have memory failure.

  • Focus on trying to write comments that aid in the readability of your source code.  Don’t think that you have to write comments that explain what the code is doing line by line, the code can do that.  Instead try and explain why a particular block of code is there and what it is being used for. Try to explain your intentions.  They are what matter.

  • With that said, where you can, try and keep your comments short and to the point.  Comments are there to supplement our source code, they are not the code itself and they are not meant to be some sort of novel.  It is far better to write your source code so that it is obvious to other people what you were trying to achieve than to have (or need) hundreds of lines of comments to explain it.

  • Make sure your comments are accurate. Many people view comments as a double-edged sword. Although having comments is better than no comments at all it can often be a close call if those comments are inaccurate or contradict the source code (trust me, it can happen). Remember that every time you add a comment to your source code you are going to have to maintain it, you’re going going to have to make sure it remains accurate and correct and consistent with the source code around it.

  • My recommendation therefore is whenever you can, restructure your source code to make it obvious what it is trying to achieve and in doing so try to eliminate the need for a comment at all. This is your first port of call.  If you have to add a comment, be ultra-sure that it adds value.

Try to keep these points in mind when you’re writing your own source code.  Also, if you have any other recommendations that you think people will find useful when writing code comments, feel free to add them below.

Photo credit: http://flic.kr/p/PRifp