Coding Guidelines for Cocoa – iOS Development

Coding Guidelines for Cocoa – iOS tutorial

 

Naming Methods

While doing coding it is very important to use proper naming conventions for methods, parameters and classes. This is helpful to maintain the code. This iOS tutorial will give some guidelines.

Basic Rules

Below are some basic rules that must be keep in mind while doing coding.

  1. Start the name with a lowercase letter and capitalize the first letter of embedded words. Don’t use prefixes.
    There are two specific exceptions to these guidelines. You may begin a method name with a well-known acronym in uppercase (such as TIFF or PDF)), and you may use prefixes to group and identify private methods (see Private Methods).
  2. For methods that represent actions an object takes, start the name with a verb:
    1
    2
    - (void)invokeWithTarget:(id)target;
    - (void)selectTabViewItem:(NSTabViewItem *)tabViewItem

    Do not use “do” or “does” as part of the name because these auxiliary verbs rarely add meaning. Also, never use adverbs or adjectives before the verb.

  3. If the method returns an attribute of the receiver, name the method after the attribute. The use of “get” is unnecessary, unless one or more values are returned indirectly.
    (NSSize)cellSize; Right.
    (NSSize)calcCellSize; Wrong.
    (NSSize)getCellSize; Wrong.
  4. Use keywords before all arguments.
    (void)sendAction:(SEL)aSelector toObject:(id)anObject forAllCells:(BOOL)flag; Right.
    (void)sendAction:(SEL)aSelector :(id)anObject :(BOOL)flag; Wrong.
  5. Make the word before the argument describe the argument.
    (id)viewWithTag:(NSInteger)aTag; Right.
    (id)taggedView:(int)aTag; Wrong.
  6. Add new keywords to the end of an existing method when you create a method that is more specific than the inherited one.
    (id)initWithFrame:(CGRect)frameRect; NSView, UIView.
    (id)initWithFrame:(NSRect)frameRect mode:(int)aMode cellClass:(Class)factoryId numberOfRows:(int)rowsHigh numberOfColumns:(int)colsWide; NSMatrix, a subclass of NSView
  7. Don’t use “and” to link keywords that are attributes of the receiver.
    (int)runModalForDirectory:(NSString *)path file:(NSString *) name types:(NSArray *)fileTypes; Right.
    (int)runModalForDirectory:(NSString *)path andFile:(NSString *)name andTypes:(NSArray *)fileTypes; Wrong.
  8. If the method describes two separate actions, use “and” to link them.
    (BOOL)openFile:(NSString *)fullPath withApplication:(NSString *)appName andDeactivate:(BOOL)flag; NSWorkspace.

Accessor Methods

Accessor methods are those methods that set and return the value of a property of an object. They have certain recommended forms, depending on how the property is expressed:

    • If the property is expressed as a noun, the format is:
      – (type)noun;- (void)setNoun:(type)aNoun;For example:

      1
      2
      - (NSString *)title;
      - (void)setTitle:(NSString *)aTitle;
    • If the property is expressed as an adjective, the format is:
      – (BOOL)isAdjective;- (void)setAdjective:(BOOL)flag;For example:

      1
      2
      - (BOOL)isEditable;
      - (void)setEditable:(BOOL)flag;
    • If the property is expressed as a verb, the format is:
      – (BOOL)verbObject;- (void)setVerbObject:(BOOL)flag;For example:

      1
      2
      - (BOOL)showsAlpha;
      - (void)setShowsAlpha:(BOOL)flag;

      The verb should be in the simple present tense.

    • Don’t twist a verb into an adjective by using a participle:
      (void)setAcceptsGlyphInfo:(BOOL)flag; Right.
      (BOOL)acceptsGlyphInfo; Right.
      (void)setGlyphInfoAccepted:(BOOL)flag; Wrong.
      (BOOL)glyphInfoAccepted; Wrong.
    • You may use modal verbs (verbs preceded by “can”, “should”, “will”, and so on) to clarify meaning, but don’t use “do” or “does”.
      (void)setCanHide:(BOOL)flag; Right.
      (BOOL)canHide; Right.
      (void)setShouldCloseDocument:(BOOL)flag; Right.
      (BOOL)shouldCloseDocument; Right.
      (void)setGlyphInfoAccepted:(BOOL)flag; Wrong.
      (BOOL)glyphInfoAccepted; Wrong.
    • Use “get” only for methods that return objects and values indirectly. You should use this form for methods only when multiple items need to be returned.
      (void)getLineDash:(float *)pattern count:(int *)count phase:(float *)phase; NSBezierPath

      In methods such as these, the implementation should accept NULL for these in–out parameters as an indication that the caller is not interested in one or more of the returned values.

Delegate Methods

Delegate methods (or delegation methods) are those that an object invokes in its delegate (if the delegate implements them) when certain events occur. They have a distinctive form, which apply equally to methods invoked in an object’s data source:

        • Start the name by identifying the class of the object that’s sending the message:
          1
          2
          - (BOOL)tableView:(NSTableView *)tableView shouldSelectRow:(int)row;
          - (BOOL)application:(NSApplication *)sender openFile:(NSString *)filename;

          The class name omits the prefix and the first letter is in lowercase.

        • A colon is affixed to the class name (the argument is a reference to the delegating object) unless the method has only one argument, the sender.
          1
          - (BOOL)applicationOpenUntitledFile:(NSApplication *)sender;
        • An exception to this are methods that invoked as a result of a notification being posted. In this case, the sole argument is the notification object.
          1
          - (void)windowDidChangeScreen:(NSNotification *)notification;
        • Use “did” or “will” for methods that are invoked to notify the delegate that something has happened or is about to happen.
          1
          2
          - (void)browserDidScroll:(NSBrowser *)sender;
          - (NSUndoManager *)windowWillReturnUndoManager:(NSWindow *)window;
        • Although you can use “did” or “will” for methods that are invoked to ask the delegate to do something on behalf of another object, “should” is preferred.
          1
          - (BOOL)windowShouldClose:(id)sender;

Private Methods

In most cases, private method names generally follow the same rules as public method names. However, a common convention is to give private methods a prefix so it is easy to distinguish them from public methods. Even with this convention, the names given to private methods can cause a peculiar type of problem. When you design a subclass of a Cocoa framework class, you cannot know if your private methods unintentionally override private framework methods that are identically named.

Names of most private methods in the Cocoa frameworks have an underscore prefix (for example, _fooData ) to mark them as private. From this fact follow two recommendations.

Don’t use the underscore character as a prefix for your private methods. Apple reserves this convention.
If you are subclassing a large Cocoa framework class (such as NSView or UIView) and you want to be absolutely sure that your private methods have names different from those in the superclass, you can add your own prefix to your private methods. The prefix should be as unique as possible, perhaps one based on your company or project and of the form “XX_”. So if your project is called Byte Flogger, the prefix might be BF_addObject:
Although the advice to give private method names a prefix might seem to contradict the earlier claim that methods exist in the namespace of their class, the intent here is different: to prevent unintentional overriding of superclass private methods.

 

Read More – https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/CodingGuidelines/Articles/NamingMethods.html

Leave a Reply

Your email address will not be published. Required fields are marked *


CAPTCHA Image
Reload Image