Общие принципы

Ясность

• Хорошо быть и ясным и кратким как возможное, но ясность не должна страдать из-за краткости:

  Код	Комментарий
  insertObject:atIndex:	Хороший.
  insert:at:	Не ясный; что вставляется? что делает «в», имеют значение?
  removeObjectAtIndex:	Хороший.
  removeObject:	Хороший, потому что это удаляет объект, упомянутый в параметре.
  remove:	Не ясный; что удаляется?

• В целом не сокращайте имена вещей. Обстоятельно объясните их, даже если они длинны:

  Код	Комментарий
  destinationSelection	Хороший.
  destSel	Не ясный.
  setBackgroundColor:	Хороший.
  setBkgdColor:	Не ясный.

  Можно думать, что сокращение известно, но это не могло бы быть, особенно если у разработчика, встречающегося именем метода или именем функции, есть различный культурный и лингвистический фон.

• Однако ряд сокращений действительно распространен и имеет долгую историю использования. Можно продолжать использовать их; посмотрите Приемлемые Сокращения и Акронимы.

• Избегите неоднозначности на имена API, такие как имена методов, которые могли быть интерпретированы больше чем одним способом.

  Код	Комментарий
  sendPort	Это отправляет порт или возвращает его?
  displayName	Это выводит на экран имя или возвращает заголовок получателя в пользовательском интерфейсе?

Непротиворечивость

• Попытайтесь использовать имена последовательно всюду по Какао программируемые интерфейсы. Если Вы не уверены, просматриваете текущие заголовочные файлы или справочную документацию для прецедентов.

• Непротиворечивость особенно важна, когда у Вас есть класс, методы которого должны использовать в своих интересах полиморфизм. Методы, делающие ту же вещь в различных классах, должны иметь то же имя.

  Код	Комментарий
  - (NSInteger)tag	Определенный в NSView, NSCell, NSControl.
  - (void)setStringValue:(NSString *)	Определенный во многих классах Какао.

См. также Аргументы метода.

Нет сам ссылка

• Имена не должны быть самосправочными.

  Код	Комментарий
  NSString	Хорошо.
  NSStringObject	Самосправочный.

• Константы, которые являются масками (и таким образом может быть объединен в битовых операциях) являются исключением к этому правилу, как константы для имен уведомления.

  Код	Комментарий
  NSUnderlineByWordMask	Хорошо.
  NSTableViewColumnDidMoveNotification	Хорошо.

Префиксы

Префиксы являются важной частью имен в программируемых интерфейсах. Они дифференцируют функциональные области программного обеспечения. Обычно это программное обеспечение прибывает упакованное в платформу или (как имеет место Набора Основы и Приложения) в тесно связанных платформах. Префиксы защищают от коллизий между символами, определенными сторонними разработчиками и определенными Apple (а также между символами в собственных платформах Apple).

• Префикс имеет предписанный формат. Это состоит из двух или трех прописных букв и не использует подчеркивания или “sub префиксы”. Вот некоторые примеры:

  Префикс	Платформа какао
  NS	Основа
  NS	Набор приложения
  AB	Адресная книга
  IB	Интерфейсный разработчик

• Используйте префиксы когда классы идентификатора, протоколы, функции, константы, и typedef структуры. Не используйте префиксы при именовании методов; методы существуют в пространстве имен, создаваемом классом, определяющим их. Кроме того, не используйте префиксы для именования полей структуры.

Типографские условные обозначения

Следуйте нескольким простым соглашениям о правилах печати при именовании элементов API:

• Для имен, составленных из многократных слов, не используйте знаки препинания в качестве частей имен или в качестве разделителей (подчеркивания, тире, и т.д.); вместо этого, капитализируйте первую букву каждого слова и выполните слова вместе (например, runTheWordsTogether) — это известно как преобразование регистра верблюда. Однако отметьте следующие квалификации:

  • Для имен методов запустите со строчной буквы и капитализируйте первую букву встроенных слов. Не используйте префиксы.

    fileExistsAtPath:isDirectory:

    Исключение к этой инструкции является именами методов, запускающимися с известного акронима, например, TIFFRepresentation (NSImage).

  • Для имен функций и констант, используйте тот же префикс что касается связанных классов и капитализируйте первую букву встроенных слов.

    NSRunAlertPanel

    NSCellDisabled

• Избегите использования символа подчеркивания как префикс, означающий частный в именах методов (использующий символ подчеркивания в качестве префикса для имени переменной экземпляра, позволяется). Apple резервирует использование этого соглашения. Использование третьими лицами могло привести к конфликтам пространства имен; они могли бы невольно переопределить существующий закрытый метод с одним собственным с катастрофическими последствиями. Посмотрите Закрытые методы для предложений на соглашениях следовать для частного API.

Класс и имена протокола

Имя класса должно содержать существительное, ясно указывающее то, что класс (или объекты класса) представляют или делают. Имя должно иметь надлежащий префикс (см. Префиксы). Основа и среды разработки приложения полны примеров; некоторые NSString, NSDate, NSScanner, NSApplication, UIApplication, NSButton, и UIButton.

Протоколы нужно назвать согласно тому, как они группируют способы поведения:

• Большая часть группы протоколов связала методы, не связанные ни с каким классом в частности. Этот тип протокола нужно назвать так, чтобы протокол не был перепутан с классом. Общее соглашение состоит в том, чтобы использовать герундий (“... луг”) форма:

  Код	Комментарий
  NSLocking	Хороший.
  NSLock	Плохой (походит на имя для класса).

• Некоторая группа протоколов много несвязанных методов (а не создают несколько отдельных маленьких протоколов). Эти протоколы имеют тенденцию быть связанными с классом, который является основным выражением протокола. В этих случаях соглашение состоит в том, чтобы дать протоколу то же имя как класс.

  Пример этого вида протокола NSObject протокол. Эти методы групп протокола, которые можно использовать, чтобы запросить любой объект о его позиции в иерархии классов, заставить его вызвать определенные методы, и постепенно увеличить или постепенно уменьшить ее подсчет ссылок. Поскольку NSObject класс обеспечивает первичное выражение этих методов, протокол называют в честь класса.

Заголовочные файлы

То, как Вы называете заголовочные файлы, важно, потому что соглашение, которое Вы используете, указывает то, что содержит файл:

• Объявление изолированного класса или протокола. Если класс или протокол не являются частью группы, поместите ее объявление в отдельный файл, имя которого является именем заявленного класса или протокола.

  Заголовочный файл	Объявляет
  NSLocale.h	NSLocale класс.

• Объявление связанных классов и протоколов. Для группы связанных объявлений (классы, категории, и протоколы), помещает объявления в файл, носящий имя основного класса, категории или протокола.

  Заголовочный файл	Объявляет
  NSString.h	NSString и NSMutableString классы.
  NSLock.h	NSLocking протокол и NSLock, NSConditionLock, и NSRecursiveLock классы.

• Включая заголовочные файлы платформы. Каждая платформа должна иметь заголовочный файл, названный в честь платформы, включающей все общедоступные заголовочные файлы платформы.

  Заголовочный файл	Платформа
  Foundation.h	Foundation.framework.

• Добавление API к классу в другой платформе. Если Вы объявляете методы в одной платформе, которые находятся в категории на классе в другой платформе, добавляют «Дополнения» к имени исходного класса; пример NSBundleAdditions.h заголовочный файл Набора Приложения.

• Связанные функции и типы данных. Если Вы имеете группу связанных функций, констант, структур, и других типов данных, помещаете их в соответственно именованный заголовочный файл такой как NSGraphics.h (Набор приложения).