Google objective-c Coding style (3) Comment

Comments

Although it is painful to write, annotations are the key to keeping your code readable. The following rules give you an explanation of when and where you should comment. Remember: Although annotations are important, the best code should be self-documenting. Instead of having an obscure name for a type or variable, write a comment about it, rather than just a meaningful name.

When you write a note, remember that you are writing to your audience, the next contributor who needs to read the code you are writing. Be generous, the next person reading the code may be you!

Keep in mind that the rules in all C + + style guides also apply here, and the different places will be gradually pointed out later.

File comments

Tip

The beginning of each file starts with a brief description of the contents of the file, followed by the author, and finally the copyright notice and/or license template.

Copyright Information and Authors

Each file should include the following in order:

• Brief description of the contents of the document
• Code author
• Copyright information Statement (e.g., Google Inc.)
• If necessary, add the license template. Choose an appropriate authorization template for your project (for example,Apache 2.0, BSD, LGPL, GPL).

If you make significant changes to other people's original code, please add your own name to the author. When another code contributor has a problem with the file, he needs to know how to contact you, which is useful.

Comments in the Declarations section

Tip

Each interface, category, and protocol should be supplemented with annotations to describe its purpose and its relationship to the entire project.

A delegate for NSApplication to handle notifications about app//launch and shutdown. Owned by the main app controller. ... }@end   

If you have described the interface in detail at the head of the file, you can directly describe the "full description See file Header", but be sure to have this part of the comment.

In addition, each method of the public interface should have a comment explaining its function, parameters, return value, and other effects.

Comment on the thread safety of the class, if any. If an instance of a class can be accessed by multiple threads, remember to annotate the usage rules under multithreaded conditions.

Annotations for the Implementation section

Tip

Use | to refer to variable names and symbolic names in comments instead of using quotation marks.

This avoids ambiguity, especially when the symbol is a common term, which is poorly read using a statement. For example, for symbol count :

Sometimes we need |count| To is less than zero.

Or when referencing a symbol that already contains quotation marks:

Remember to call | Stringwithoutspaces ("foo bar baz") |

Object ownership

Tip

When the most conventional approach to objective-c is not the same, try to make the pointer ownership model as clear as possible.

An instance variable pointer to an object that inherits from NSObject , usually assumed to be a strong reference relationship (retained), or, in some cases, a weak reference (weak) or a __weak life-cycle qualifier. Similarly, if the declared property is not retainedby the class, it must be specified as a weak reference or given @property property. However, the iboutlets instance variables that are marked on the MAC software are considered not to be retained by the class.

When an instance variable points to corefoundation, C + +, or other non-objective-c objects, you need to use __strong and __ Regardless of whether the pointer is retained. The weak type modifier is explicitly specified. Corefoundation and other non-OBJECTIVE-C object pointers require explicit memory management, even if an automatic reference count or garbage collection mechanism is used. When the __weak type modifier is not allowed (for example, C + + member variables at compile time with clang), a comment substitution description should be used.

Note: The automatic encapsulation of C + + objects in the Objective-c object is not allowed by default, see the instructions here.

Examples of strong and weak reference declarations:

@interfaceMyDelegate:NSObject{@privateIboutletNsbutton*Okbutton_;Normal NSControl; Implicitly weak on Mac onlyAnobjcobject*Doohickey_;My Doohickey__weakMyobjcparent*Parent_;So we can send msgs back (owns me)Non-nsobject pointers ...__strong cwackycppclass *wacky_//some Cross-platform object __strong cfdictionaryref *dict_;}  @property  (strongnonatomic< Span class= "P" >) nsstring *doohickey; @property  (weaknonatomic) nsstring *parent; @end                  

The strong reference-object is retainedby class. Weak references-objects are not retainedby class, such as delegates)

Google objective-c Coding style (3) Comment