{"id":20504470,"url":"https://github.com/tiknil/objective-c-style-guide","last_synced_at":"2026-03-10T03:32:16.389Z","repository":{"id":41075224,"uuid":"45740235","full_name":"tiknil/objective-c-style-guide","owner":"tiknil","description":"Tiknil's style guide \u0026 coding conventions for Objective-C projects","archived":false,"fork":false,"pushed_at":"2015-11-25T08:19:50.000Z","size":17,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-01-16T07:54:28.163Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"http://www.tiknil.com","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tiknil.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-11-07T14:42:47.000Z","updated_at":"2015-11-19T14:12:21.000Z","dependencies_parsed_at":"2022-08-29T07:40:38.344Z","dependency_job_id":null,"html_url":"https://github.com/tiknil/objective-c-style-guide","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tiknil%2Fobjective-c-style-guide","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tiknil%2Fobjective-c-style-guide/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tiknil%2Fobjective-c-style-guide/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tiknil%2Fobjective-c-style-guide/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tiknil","download_url":"https://codeload.github.com/tiknil/objective-c-style-guide/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":242101954,"owners_count":20071978,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-15T19:38:12.971Z","updated_at":"2026-03-10T03:32:11.346Z","avatar_url":"https://github.com/tiknil.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# objective-c-style-guide #\n\n:exclamation: DRAFT :exclamation:\n\n\nGuida di riferimento per i progetti Objective-C in Tiknil. \nNon vuole essere l'ennesima riproposizione dello stile di stesura dei progetti in questo linguaggio, ma uno strumento utile per il team e i suoi collaboratori. \n\nSentitevi liberi di dissentire da quanto abbiamo deciso di tenere come stile guida! :wink:\n\n### TL;DR ###\n\nTroppo lunga da leggere? E' solo l'ennesima guida di stile di Obj-C? \nOk, passiamo al dunque, nerd: usa i tool che ti elenchiamo per cominciare a 'subire' un po' di codice di qualità: \n\n1) [XCode snippets](https://github.com/tiknil/xcode-snippets) - dovresti leggere perché usarli, almeno\n\n2) Installa `BBUncrustifyPlugin` tramite [Alcatraz](http://alcatraz.io/) e usa il file `uncrustify.cfg` che trovi nel presente repo. Tranquilli, è tutto ben descritto in [Tools](#tools).\n\n### References ###\n\nDi seguito le linee guida che abbiamo consultato e a cui facciamo riferimento per la stesura di questo documento: \n* [Apple coding guidelines](https://developer.apple.com/library/mac/documentation/Cocoa/Conceptual/CodingGuidelines/CodingGuidelines.html)\n* [Ray Wenderlich Obj-C style guide](https://github.com/raywenderlich/objective-c-style-guide)\n* [NY Times Obj-C style guide](https://github.com/NYTimes/objective-c-style-guide)\n* [GitHub Obj-C style guide](https://github.com/github/objective-c-style-guide)\n* [Google Obj-C style guide](https://google.github.io/styleguide/objcguide.xml)\n\n### Concetti di base ###\n\nPerché abbiamo preso certe scelte e non altre? Ecco i concetti che guidano alcune scelte esposte in questa guida (in ordine non per forza di priorità): \n* [Bellezza](https://it.wikipedia.org/wiki/Bellezza) e stile uniforme, anche nel codice\n* Comprensibilità del codice da chiunque\n* Velocità di scrittura del codice\n* Produzione della documentazione in Italiano\n* Somiglianze con altri linguaggi che utilizziamo per i progetti\n* Abitudini nostre (in via di miglioramento)\n\n### Sommario ###\n1. [Lingua](#lingua)\n2. [Organizzazione implementazione delle classi](#organizzazione-implementazione-delle-classi)\n3. [Commenti](#commenti)\n4. [Naming](#naming)\n  * [Dichiarazione dei metodi](#dichiarazione-dei-metodi)\n  * [Variabili](variabili)\n  * [Attributi delle `@property`](#attributi-delle-property)\n  * [Underscores](#underscores)\n  * [Categories](#categories)\n5. [Literals](#literals)\n\n[Tools](#tools)\n\n### Lingua ###\nUsare la lingua **Inglese** per il **codice**, quella **Italiana** per i **commenti** e la **documentazione** del codice (ove non espressamente richiesta la lingua inglese)\n\n:+1: `UIColor *myColor = [UIColor whiteColor];`\n\n:-1: `UIColor *mioColore = [UIColor whiteColor];`\n\n### Organizzazione implementazione delle classi ###\n\nRaccomandato l'uso dei ```#pragma mark```per raggruppare i metodi in gruppi funzionali e legati all'implementazione dei protocolli/delegati seguendo la struttura seguente (da [RW Obj-C style guide](https://github.com/raywenderlich/objective-c-style-guide)): \n\n```\n#pragma mark - Class methods\n+ (instancetype) shared;\n\n#pragma mark - Lifecycle\n\n- (instancetype)init {}\n- (void)dealloc {}\n- (void)viewDidLoad {}\n- (void)viewWillAppear:(BOOL)animated {}\n- (void)didReceiveMemoryWarning {}\n\n#pragma mark - Custom Accessors\n\n- (void)setCustomProperty:(id)value {}\n- (id)customProperty {}\n\n#pragma mark - IBActions\n\n- (IBAction)submitData:(id)sender {}\n\n#pragma mark - Public\n\n- (void)publicMethod {}\n\n#pragma mark - Private\n\n- (void)privateMethod {}\n\n#pragma mark - Protocol conformance\n#pragma mark - UITextFieldDelegate\n#pragma mark - UITableViewDataSource\n#pragma mark - UITableViewDelegate\n\n#pragma mark - NSCopying\n\n- (id)copyWithZone:(NSZone *)zone {}\n\n#pragma mark - NSObject\n\n- (NSString *)description {}\n```\n\nPer semplificare l'utilizzo dell'organizzazione del codice come descritto consigliamo di utilizzare lo *snippet* di XCode apposito come descritto nel repo [Xcode-snippets](https://github.com/tiknil/xcode-snippets): basta digitare ```def``` quando si sta per stendere l'implementazione di una nuova classe.\n\n![def code snippet](https://github.com/tiknil/xcode-snippets/blob/master/images/def_code_snippet.gif)\n\n### Commenti ###\n\nPer scrivere codice di qualità i commenti sono fondamentali: essi rientrano nei [requisiti non funzionali o di qualità (ISO IEC 9126)](https://it.wikipedia.org/wiki/ISO/IEC_9126) di tutti i progetti sofware all'interno della voce \"Manutenibilità\".\n\n* I commenti, quando necessari, devono spiegare perché una particolare parte di codice fa qualcosa. Ogni commento che è utilizzato dev'essere sempre aggiornato o eliminato.\n* Preferire codice auto-esplicativo (dando nomi significativi alle variabili e ai metodi, vedi [Naming](#naming), se possibile, rispetto ai commenti. Nel dubbio, metterli entrambi.\n\nCome commentare? Ecco un ottimo (e breve) articolo su NSHipster relativo alla documentazione Obj-C [Documentation](http://nshipster.com/documentation/)\n```\n/**\n Questo è un commento\n */\n```\n\ne\n\n```\n/**\n Questo è il commento alla dichiarazione di questo metodo che ha come parametro paramValue e che ritorna come risultato resultValue\n @param paramValue il parametro passato a questo metodo\n @result resultValue il risultato che viene ritornato x o y in base al parametro\n */\n```\n\nNon sei sicuro di riuscire a ricordarti sempre come scrivere i commenti? Fatti aiutare dagli [snippets `com`...](https://github.com/tiknil/xcode-snippets)!\n\n### Naming ###\n\nFare riferimento alle [linee guida Apple](https://developer.apple.com/library/mac/documentation/Cocoa/Conceptual/CodingGuidelines/Articles/NamingBasics.html#//apple_ref/doc/uid/20001281-BBCHBFAH) riprese anche da [RW](https://github.com/raywenderlich/objective-c-style-guide/blob/master/README.md#naming) per cui: \n\nI nomi dei metodi e delle variabili devono essere descrittivi, va bene anche se sono lunghi\n\n:+1: `UIButton *settingsButton;`\n\n:-1: `UIButton *setBut;`\n\nLe costanti devono essere *camel-case* con tutte le parole con la prima lettera maiuscola e devono iniziare con il nome della classe a cui fanno riferimento (se lo fanno).\n\n:+1: `static NSTimeInterval const RWTTutorialViewControllerNavigationFadeAnimationDuration = 0.3;`\n\n:-1: `static NSTimeInterval const fadetime = 1.7;`\n\nI campi (`@property`) delle classi devono essere *camel-case* con la prima lettera minuscola. Preferire l'auto-sintesi dei campi piuttosto che scrivere manualmente i `@synthesize` a meno che ci sia una buona ragione. \n\n:+1: `@property (strong, nonatomic) NSString *descriptiveVariableName;`\n\n:-1: `id varnm;`\n\n#### Dichiarazione dei metodi ####\n\nI nomi dei metodi devono essere descrittivi, come già detto nel paragrafo precedente. I parametri formali del metodo devono essere separati da uno spazio (come da stile Apple). Aggiungere sempre un nome per il parametro e descrivere a cosa serve quel parametro.\nNon usare le parole 'and' e 'with' o similari, come descritto in questi esempi:\n\n:+1:\n\n```\n- (void) setExampleText:(NSString *)text image:(UIImage *)image;\n- (void) sendAction:(SEL)aSelector to:(id)anObject forAllCells:(BOOL)flag;\n- (id) viewWithTag:(NSInteger)tag;\n- (instancetype) initWithWidth:(CGFloat)width height:(CGFloat)height;\n```\n\n:-1:\n\n```\n- (void) setT:(NSString *)text i:(UIImage *)image;\n- (void) sendAction:(SEL)aSelector :(id)anObject :(BOOL)flag;\n- (id) taggedView:(NSInteger)tag;\n- (instancetype) initWithWidth:(CGFloat)width andHeight:(CGFloat)height;\n- (instancetype) initWith:(int)width and:(int)height;  // Never do this.\n```\n\n#### Variabili ####\n\nLe variabili devono essere il più descrittive possibile. L'uso di variabili con una sola lettera è ammesso solo per i cicli `for`.\n\nDove si mette l'asterisco per le variabili che puntano ad un oggetto? \n\n:+1: `NSString *text`\n\n:-1: `NSString* text` or `NSString * text` (tranne che per le costanti)\n\nSi preferisce l'uso delle `@property` private piuttosto che d'istanza. Per `@property` private si intende quelle con definizione nel file `.m` in una categoria detta **anonima** (indicata dal fatto che è descritta con `()`): \n\n```\ninterface RWTDetailViewController ()\n\n@property (strong, nonatomic) GADBannerView *googleAdView;\n@property (strong, nonatomic) ADBannerView *iAdView;\n@property (strong, nonatomic) UIWebView *adXWebView;\n\n@end\n```\n\nSi preferisce usare le `@property` private piuttosto che i campi d'istanza. Questo vale anche per i campi `IBOutlet` generati (o predisposti) da drag\u0026drop a partire da Interface Builder: di default vanno messi come `@property` privata nel file `.m`; qualora sia necessario averli pubblici, allora verranno spostati nel `.h`.\n\n:+1:\n\n```\n@interface RWTTutorial : NSObject\n\n@property (strong, nonatomic) NSString *tutorialName;\n\n@end\n```\n\n:-1:\n\n```\n@interface RWTTutorial : NSObject {\n  NSString *tutorialName;\n}\n```\n\nCome descritto in [Underscores](#underscores) si preferisce non accedere direttamente alle `@property` se non nei metodi di 'Lifecicle' dell'oggetto (`init`, `dealloc`, etc) e nei 'custom accessors'.\n\n#### Attributi delle `@property` ####\n\nGli attributi delle property devono essere scritti perché servono ed aiutano chi legge il codice a comprenderlo meglio. L'ordine degli attributi deve essere: storage \u003e atomicity così da essere coerente con il codice generato da Interface Builder quando si trascinano i collegamenti agli elementi UI. \n\n:+1:\n\n```\n@property (weak, nonatomic) IBOutlet UIView *containerView;\n@property (strong, nonatomic) NSString *tutorialName;\n```\n\n:-1:\n\n```\n@property (nonatomic, weak) IBOutlet UIView *containerView;\n@property (nonatomic) NSString *tutorialName;\n```\n\nPreferire **`strong`** a **`retain`** (che sono la stessa cosa: [SO answer](http://stackoverflow.com/questions/8927727/objective-c-arc-strong-vs-retain-and-weak-vs-assign) - [Apple Doc](https://developer.apple.com/library/mac/releasenotes/ObjectiveC/RN-TransitioningToARC/Introduction/Introduction.html)) per migliore formattazione del codice\n\nUsare sempre **`weak`** per gli oggetti `IBOutlet`. Ti chiedi perché? Fattelo spiegare da [NSHipster](http://nshipster.com/ibaction-iboutlet-iboutletcollection/) e dalla [Resource Programming Guide section on Nib Files di Apple](https://developer.apple.com/library/mac/documentation/Cocoa/Conceptual/LoadingResources/CocoaNibs/CocoaNibs.html). \n\nLa [RW Obj-C style guide](https://github.com/raywenderlich/objective-c-style-guide/blob/master/README.md#error-handling) suggerisce di utilizzare **`copy`** piuttosto di **`strong`** per avere la certezza che la `@property` non venga mutata una volta assegnata. Chiaramente dipende dal contesto, quindi valutate di conseguenza\n\n#### Underscores ####\n\nQuando si usano i campi (`@property`) d'istanza essi devono essere sempre richiamati usando `self.`. Questo rende più evidente in maniera visiva l'utilizzo dei campi d'istanza.\n\nFa eccezione l'utilizzo dei campi con *underscore* (`_variableName`) nei metodi `init` o nei metodi getter/setter che ne richiedano l'utilizzo per il corretto funzionamento.\n\nLe variabili locali **non devono contenere underscore**.\n\n#### Categories ####\n\nLe categories devono avere nomi che ne definiscano la funzionalità. Attenzione a non creare categories che fanno uso di altre categories (il debug potrebbe diventare arduo).\n\n:+1: `@interface NSString (StringEncodingDetection)`\n\n:-1: `@interface NSString (Utilities)`\n\n_I metodi delle category devono avere sempre il prefisso seguito da underscore._ Questo limita la possibilità di creare eventuali duplicati di metodi esistenti tra le varie librerie.\n\n`- (NSStringEncoding) sed_detectStringEncoding:(NSString*)string;`\n\nSe hai necessità di esporre dei metodi privati per delle sottoclassi o per fare test crea una categories chiamata `Class+Private`\n\n### Literals ###\n\nPreferire sempre l'uso dei literals piuttosto delle descrizioni estese per gli oggetti del framework, in particolare `NSString`, `NSDictionary`, `NSArray` e `NSNumber`: \n\n:+1:\n\n```\nNSArray *names = @[@\"Brian\", @\"Matt\", @\"Chris\", @\"Alex\", @\"Steve\", @\"Paul\"];\nNSDictionary *productManagers = @{@\"iPhone\": @\"Kate\", @\"iPad\": @\"Kamal\", @\"Mobile Web\": @\"Bill\"};\nNSNumber *shouldUseLiterals = @YES;\nNSNumber *buildingStreetNumber = @10018;\n```\n\n:-1:\n\n```\nNSArray *names = [NSArray arrayWithObjects:@\"Brian\", @\"Matt\", @\"Chris\", @\"Alex\", @\"Steve\", @\"Paul\", nil];\nNSDictionary *productManagers = [NSDictionary dictionaryWithObjectsAndKeys: @\"Kate\", @\"iPhone\", @\"Kamal\", @\"iPad\", @\"Bill\", @\"Mobile Web\", nil];\nNSNumber *shouldUseLiterals = [NSNumber numberWithBool:YES];\nNSNumber *buildingStreetNumber = [NSNumber numberWithInteger:10018];\n```\n\n### Tools ###\n\nPer noi è importante trovare i tool che ci permettano di mantenere certe scelte in modo costante e coerente di progetto in progetto. Partecipando ad un interessante *talk* di Anastasia Kazakova (@anastasiak2512) alla #Pragma conf 2015 a Firenze abbiamo visto che IDE come AppCode integrano strumenti per la formattazione del codice in modo avanzato ma tramite alcuni plugin e risorse è possibile avere queste funzionalità anche su XCode. \n\nQuello che abbiamo trovato più completo e facile da capire è [Uncrustify](http://uncrustify.sourceforge.net/) che in XCode è facilmente intergrabile tramite il plugin [BBUncrustifyPlugin](https://github.com/benoitsan/BBUncrustifyPlugin-Xcode), installabile anch'esso tramite [Alcatraz](http://alcatraz.io/).\n\nUna volta installato basta andare in `Edit \u003e Format Code \u003e BBUncrustifyPlugin preferences`, scegliere come formatter `Uncrustify` e alla voce `Clang style` scegliere `Custom Style (File)` (se lo desiderate, altrimenti scegliete il formattatore che più vi [aggrada](https://www.youtube.com/watch?v=b3mGYIgR5_c)).\n\nAlla voce `Configuration File` dunque scegliere `Create Configuration File` e il vostro editor di testo preferito (sarà indubbiamente [Sublime Text](http://www.sublimetext.com/).\n\nPer utilizzare lo stile delineato in questa guida basta prendere il file `uncrustify.cfg` e copiarlo in una qualsiasi cartella padre della cartella del progetto di XCode che avete aperto. Il consiglio è di avere il file `uncrustify.cfg` nella cartella root dei vostri progetti iOS/OSX. \n\nSe volete fare le cose per bene, fate così: \n\n1) Fate un fork di questo repository e scaricatelo in locale nella cartella `$OBJ_C_STYLE_GUIDE_REPO`\n\n2) Quindi create un link simbolico al file `uncrustify.cfg` nella cartella root dei vostri progetti iOS/OSX\n\n```\nln -s $OBJ_C_STYLE_GUIDE_REPO/uncrustify.cfg $IOS_OSX_PROJECTS_ROOT/uncrustify.cfg\n```\n\nPer formattare un file o le righe selezionate in XCode tramite Uncrustify basterà quindi selezionare `Edit \u003e Format Code \u003e ` e scegliere `Format Selected Files`, `Format Active File` o `Format Selected Lines`. \n\nPuoi impostare gli shortcut da tastiera semplicemente nell'app `Preferences` di sistema: ![KeyBindings](http://cl.ly/image/1g3s3c3o381B/Schermata%202015-11-14%20alle%2010.35.03.png)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftiknil%2Fobjective-c-style-guide","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftiknil%2Fobjective-c-style-guide","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftiknil%2Fobjective-c-style-guide/lists"}