Good commenting practices [closed]

Closed. This question is off-topic. It is not currently accepting answers.

---

Want to improve this question? Update the question so it's on-topic for Stack Overflow.

Closed 11 years ago.

Improve this question

I just completed with one of my applications w开发者_StackOverflowhich is now ready to be tested. But before submitting my application I want to make sure I have used appropriate comments wherever required. Though I use comments in most of my applications but it is this time I have realized that my application is quite complex and thus for the purpose of reviewing the code again and for functional understanding I need proper commenting. I was also worried about the amount of commenting in my application.

What I am looking for are standard commenting practices we need to follow in IPhone development.

Kindly assist.

---

Good Comments say "why" you did something, not "what" you did.

---

I usually implement comments in the following situations, (this is by no means exhaustive), and any developer reviewing or debugging your application would appreciate them in these situations:

• When I use a third-party or otherwise obscure library;
• In deep-nested control structures when they cannot be avoided;
• When implementing my own protocols in Obj-C (when they are not obvious);
• And in general when something is not obvious to you and/or a potential reviewer

EDIT: And I also suggest implementing sparingly, if you did not get that from the post. It is annoying to read code that is near the over-commenting threshold. You do not want to feel like you are reading an introduction to programming book.

---

There is nothing special with regard to comments and iPhone development.

Personally I prefer readable (self-documenting) code over comments. That is, using meaningful method and variable names to make the purpose of the code understood. If it still can't be understood then comments might be useful, but don't make them too long. A problem with long comments is that they might fall out of sync with the sources and become misleading.

I think links to other sources of documentation are good, such as stackoverflow questions, bug databases, etc.

---

These, to me, are the golden principles:

• Comments should never explain code (use self-explanatory code with proper names and indentation).
• Don't insult the reader's intelligence with unnesseary comments
• Comment by code block (if you need to explain a process, don't use seperate comments on each line of the code block).

---

When Im commenting my code, I act as if I had some half wit programmer sitting right next to me asking me "what does this code do, and why are you doing it?" Ill reply in a nutshell of an answer.

My response to him is what I comment.

// now that we got the data we need lets store it in the Settings Array

// check for NULL if null, change to None Selected

// make sure there is an object here so we dont crash