Methods are perhaps the most common element of your programming interface, so you should take particular care in how you name them. This section discusses the following aspects of method naming:
General Rules
This section discusses the following aspects of method naming: General Rules. Here are a few general guidelines to keep in mind when naming methods: Start the name with a lowercase letter and capitalize the first letter of embedded words. Don’t use prefixes. See Typographic Conventions. There are two specific exceptions to these guidelines. This post covers OS X Bonjour naming guidelines including overview of tools for retrieving and setting the Bonjour Name on OS X, allowed characters, maximum length, and issues with using tools like scutil, systemsetup, and network setup with setting name. Nothing epitomizes this more than the convoluted naming conventions. Take yesterday’s iPad launch, for instance. Apple now offers the iPad mini, the iPad, the iPad Air and the iPad Pro. While Apple's previous iPod media players used a minimal operating system, the iPhone used an operating system based on Mac OS X, which would later be called 'iPhone OS' and then iOS. The simultaneous release of two operating systems based on the same frameworks placed tension on Apple, which cited the iPhone as forcing it to delay Mac OS X 10.
![Mac Mac](https://cdn.arstechnica.net/wp-content/uploads/2014/06/Half_Dome_from_Glacier_Point_Yosemite_NP_-_Diliff-640x402.jpg)
Here are a few general guidelines to keep in mind when naming methods:
- Start the name with a lowercase letter and capitalize the first letter of embedded words. Don’t use prefixes. See Typographic Conventions.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).
- For methods that represent actions an object takes, start the name with a verb: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.
- 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.See also Accessor Methods. - Use keywords before all arguments.
- (void)sendAction:(SEL)aSelector toObject:(id)anObject forAllCells:(BOOL)flag;
Magic bullet color. Right.- (void)sendAction:(SEL)aSelector :(id)anObject :(BOOL)flag;
Wrong. - Make the word before the argument describe the argument.
- (id)viewWithTag:(NSInteger)aTag;
Right.- (id)taggedView:(int)aTag;
Wrong. - 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 - 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.Although “and” may sound good in this example, it causes problems as you create methods with more and more keywords. - 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;
For example: - If the property is expressed as an adjective, the format is:
- (BOOL)is
Adjective;
- (void)set
Adjective:(BOOL)flag
;For example: - If the property is expressed as a verb, the format is:
- (BOOL)
verbObject;
- (void)set
VerbObject:(BOOL)flag
;For example: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)setDoesAcceptGlyphInfo:(BOOL)flag;
Wrong.- (BOOL)doesAcceptGlyphInfo;
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 acceptNULL
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: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.
- 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.
- Use “did” or “will” for methods that are invoked to notify the delegate that something has happened or is about to happen.
- 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.
Collection Methods
For objects that manage a collection of objects (each called an element of that collection), the convention is to have methods of the form:
- (void)add
Element:(
elementType)
anObj;
- (void)remove
Element:(
elementType)
anObj;
- (NSArray *)
elements;
For example:
The following are some qualifications and refinements to this guideline:
- If the collection is truly unordered, return an NSSet object rather than an NSArray object.
- If it’s important to insert elements into a specific location in the collection, use methods similar to the following instead of or in addition to the ones above:
There are a couple of implementation details to keep in mind with collection methods:
- These methods typically imply ownership of the inserted objects, so the code that adds or inserts them must retain them, and the code that removes them must also release them.
- If the inserted objects need to have a pointer back to the main object, you do this (typically) with a
set..
method that sets the back pointer but does not retain. In the case of theinsertLayoutManager:atIndex:
method, the NSLayoutManager class does this in these methods:You would normally not callsetTextStorage:
directly, but might want to override it.
Another example of the above conventions for collection methods comes from the NSWindow class:
Method Arguments
There are a few general rules concerning the names of method arguments:
- As with methods, arguments start with a lowercase letter and the first letter of successive words are capitalized (for example,
removeObject:(id)anObject
). - Don’t use “pointer” or “ptr” in the name. Let the argument’s type rather than its name declare whether it’s a pointer.
- Avoid one- and two-letter names for arguments.
- Avoid abbreviations that save only a few letters.
Traditionally (in Cocoa), the following keywords and arguments are used together:
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
orUIView
) 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 beBF_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.
Copyright © 2003, 2013 Apple Inc. All Rights Reserved. Terms of Use | Privacy Policy | Updated: 2013-10-22
Summary:
Illegal file/folder names and conventions for the following operating systems:
Windows
Mac OS 9
Mac OS X
Windows
Mac OS 9
Mac OS X
![Apple Os Naming Convention Apple Os Naming Convention](https://www.lifewire.com/thmb/jsBVjmODgc98Q9W07I2ekju9nPI=/3000x1937/filters:no_upscale():max_bytes(150000):strip_icc()/iPodGetty-571934ce5f9b58857d20d1de.jpg)
Description:
EXPLANATION & OVERVIEW
In the realm of cross-platform file sharing, sometimes the end users are not aware of the limitations posed by the operating system. This article will explain which characters can cause problems with files that use these characters.
WINDOWS CONVENTIONS
The Windows operating system can use two different file systems, Protected-Mode File Allocation Table (FAT) file system and the New Technology File System (NTFS). The two systems have much in common, but the characters permitted in a file or folder name may differ. In the conventions listed below, it is true for both systems unless otherwise specified. Specifically there are cases where NTFS does not have the limitations (see note below).
The following characters are invalid as file or folder names on Windows using NTFS:
/ ? < > : * | ' and any character you can type with the Ctrl key
/ ? < > : * | ' and any character you can type with the Ctrl key
In addition to the above illegal characters the caret ^ is also not permitted under Windows Operating Systems using the FAT file system.
Under Windows using the FAT file system file and folder names may be up to 255 characters long
Under Windows using the NTFS file system file and folder names may be up to 256 characters long
Under Window the length of a full path under both systems is 260 characters
In addition to these characters, the following conventions are also illegal:
Placing a space at the end of the name
Placing a period at the end of the name
Placing a space at the end of the name
Placing a period at the end of the name
The following file names are also reserved under Windows:
com1, com2, com3, com4, com5, com6, com7, com8, com9, lpt1, lpt2, lpt3, lpt4, lpt5, lpt6, lpt7, lpt8, lpt9, con, nul, and prn
com1, com2, com3, com4, com5, com6, com7, com8, com9, lpt1, lpt2, lpt3, lpt4, lpt5, lpt6, lpt7, lpt8, lpt9, con, nul, and prn
Note:
The previous conventions are true only if the application used in managing them is does not use the Unicode API. Although the file system may support most of the above mentioned conventions the operating system may not. For example the NTFS file system allow paths to have a length up to 32,767 characters with each component (folder, file, etc.) being limited to 255 characters. However some windows applications like Explorer, for example, may not behave correctly in this circumstance. Other software, like ExtremeZ-IP uses the Unicode API so that file and folder names with invalid characters may be stored onto the NTFS file system.
Below the Macintosh conventions will touch the fact that the colon ':' is an invalid character in the Macintosh Operating Systems. Under Windows and the NTFS file system the colon is an illegal character, because it is used to open alternate file streams. However all other characters can be moved on and off the NTFS file system if a program with Unicode support is used. Both ExtremeZ-IP and MassTransit support this Unicode filenaming convention.
The previous conventions are true only if the application used in managing them is does not use the Unicode API. Although the file system may support most of the above mentioned conventions the operating system may not. For example the NTFS file system allow paths to have a length up to 32,767 characters with each component (folder, file, etc.) being limited to 255 characters. However some windows applications like Explorer, for example, may not behave correctly in this circumstance. Other software, like ExtremeZ-IP uses the Unicode API so that file and folder names with invalid characters may be stored onto the NTFS file system.
Below the Macintosh conventions will touch the fact that the colon ':' is an invalid character in the Macintosh Operating Systems. Under Windows and the NTFS file system the colon is an illegal character, because it is used to open alternate file streams. However all other characters can be moved on and off the NTFS file system if a program with Unicode support is used. Both ExtremeZ-IP and MassTransit support this Unicode filenaming convention.
MACINTOSH OS 9 CONVENTIONS
The only illegal character for file and folder names in Mac OS 9 is the colon ':'
File and folder names may be up to 31 characters in length
MACINTOSH OS X CONVENTIONS
Since Mac OS X is build on top of UNIX there are a few inherent conventions that OS 9 users may not expect. Because of this, migrating certain files and folders from OS 9 to OS X may cause unexpected behavior.
Mac Os X 10.9.5 Nickname
The only illegal character for file and folder names in Mac OS X is the colon ':'
File and folder names are not permitted to begin with a dot '.'
File and folder names may be up to 255 characters in length
Mac Os X Version Names
EXAMPLES OF UNEXPECTED BEHAVIOR
Apple Os Naming Conventions
Below are a few scenarios that show what can happen if file names that are acceptable on one operating system are moved to another:
Example 1:
Create a file named com1 on Mac OS 9
Move the file to a Windows machine
Under Windows 2000 viewing the folder which contains the file via Explorer will result in Explorer crashing
Under Windows 2003 the file name cannot be changed because the file will require inherent access permissions
Create a file named com1 on Mac OS 9
Move the file to a Windows machine
Under Windows 2000 viewing the folder which contains the file via Explorer will result in Explorer crashing
Under Windows 2003 the file name cannot be changed because the file will require inherent access permissions
Apple Ios Names
Example 2:
Create a file named .text on Windows
Move the file to a Mac OS X machine
The file will not be visible via the Finder
(File and folder names beginning with a dot mean the file or folder is hidden)
Create a file named .text on Windows
Move the file to a Mac OS X machine
The file will not be visible via the Finder
(File and folder names beginning with a dot mean the file or folder is hidden)
Os X Names
Example 3:
Create a file named foo/ on Mac OS X
Move the file to a Windows machine
If the file is viewed via Explorer the file name will not appear as it did on the OS X machine
Create a file named foo/ on Mac OS X
Move the file to a Windows machine
If the file is viewed via Explorer the file name will not appear as it did on the OS X machine