Objective-C+iOS guia de estilo

ios-estilo.md

Guía de estilo para desarrollos iOS

Eli Kohen

Código Objective-C

Nomenclatura

Estas normas se aplicarán siempre y cuando sea posible, con la única excepción de tener que usar otra distinta porque lo exija algún framework o sea código auto-generado (véase Spring for Android, o el generador de código de WebServices).

• Al escribir nombres no se usan caracteres especiales como acentos, la Ñ, etc.

• Utilizaremos siempre nombres en inglés para variables, clases, funciones y demás. Si no sabes cómo se escribe algo, búscalo en Google Translator o en (oh, Satan, perdóname por esto) WordReference.

    // OK
    NSString* mMyAttributeName;
    // FAIL
    NSString* elNombreDeMiAtributo;

• Se utilizará siempre para el código los nombres camel case

   // OK
   NSString* myAttributeName;
   // FAIL
   NSString* el_nombre_de_mi_atributo;

• Los nombres de variables deberán ser suficientemente descriptivos como para intentar evitar, en la medida de lo posible, tener que comentar qué van a contener.

   // OK
   NSString* userName;
   // FAIL
   NSString* stuff;

• No se usarán abreviaciones ni un único carácter como nombre, salvo abreviaturas que se hayan convertido en estándar.

  • Button -> Btn
  • Label -> Lbl
  • Viewcontroler -> VC
  • Image -> Img
  • String -> Str
  • Dictionary -> Dict
  • ActivityIndicatorView -> AI
  • Array -> Array o poniendo una s (el plural) al final
  • i,j,k para iteradores en bucles

• Es aconsejable usar nombre en las variables de las vistas xib cuando hay muchas del mismo tipo y pueden llevar a confusión. Además ayuda poner el mismo nombre de su equivalente IBOutlet declarada en la interfaz (.h) de la clase (si lo hubiera)

• Constantes (#define) y macros: Siguen la nomenclatura kNOMBRE_CONSTANTE y NOMBRE_MACRO, respectivamente.

   // OK
   #define kBASE_URL @"http://thebaseurl.com"
   #define IS_IPHONE_5 ( fabs( ( double )[ [ UIScreen mainScreen ] bounds ].size.height - ( double )568 ) < DBL_EPSILON )
   // FAIL
   #define baseUrl @"http://thebaseurl.com"
   #define kIsIphone5 ( fabs( ( double )[ [ UIScreen mainScreen ] bounds ].size.height - ( double )568 ) < DBL_EPSILON )

• Declarar las variables de instancia con una m (Para seguir la costumbre de android) al inicio del nombre, para diferenciarla de variables locales y poder autocompletar en el código poniendo directamente la m.

Ordenacion de código

• Las lineas no pueden tener más de 140 caracteres (Se puede configurar en las preferencias del Xcode para que muestre una linea vertical en el editor). Podrá haber excepciones tipo urls muy largas, tampoco vamos a complicarnos en exceso para conseguir esto.

• Cuando el nombre de un método no quepa en una linea de 140 y hay que pasar parte del código una linea más abajo, se bajan todas las divisiones del método separados por los parámetros.

• Los IBOutlet se ponen todos en los property, de la mismo forma que los coloca el propio xcode cuando haces ctrl+arrastrar el elemento al .h

• En la declaración de una clase se pone primero los métodos IBAction y a continuación el resto.

• Dentro de la definición de una clase el orden en el que se colocan los métodos es:

  • Constructores y/ó inicializadores.
  • Método dealloc. (si se utiliza ya que con arc no es necesario)
  • Métodos heredados de la clase padre.
  • Métodos de la clase: primero públicos (declarados en el .h) y luego privados. Estos a su vez en el orden en el que han sido declarados.
  • Resto de métodos (protocolos, resto de herencia, etc.)

• Los métodos privados se declararán sin interfaz, ni en la parte pública ni en la privada.

• Los separadores #pragma se usaran para delimitar los distintos grupos de métodos y SIEMPRE que indiquen metodos sobrecargados o implementaciones de un protocolo se pondrá el nombre de la clase padre o protocolo tal cual es (ya que de esta forma podremos saltar haciendo click ahi)

   //OK
   #pragma mark - UIViewController inherited methods
   #pragma mark - UITableViewDelegate methods
   //FAIL
   #pragma mark - ViewController
   #pragma mark - Metodos del delegado del TableView	

• Los protocolos se declaran antes de la declaración de la interfaz de la clase, siempre que sea posible.

• La cabecera de un método no debe tener ningún espacio, salvo al inicio tras el guión, tras un asterisco de puntero y al final antes de la llave de apertura (las cuales se ponen arriba). Una llave de apertura se sitúa arriba a la derecha del inicio del bloque y la de fin en la última linea. Se deja un salto de linea tras la llave de apertura.

   //OK
   - (Hotel +)newHotel {
   	...
   }
  
   //FAIL
   -(Hotel +) newHotel
   {
   	...
   }	

• Entre bloques (por ejemplo métodos) se deja un único salto de linea (si se prefiere se puede poner una linera de comentarios que separe claramente)

   //OK
   // Hotel creator
   - (Hotel +)newHotel {
   	...
   }
   // Motel creator
   - (Motel +)newMotel {
   	...
   }
  
   //FAIL
   - (Hotel +)newHotel {
   	...
   }
   - (Motel +)newMotel {
   	...
   }	

• Poner siempre llaves en los bloques if. Como excepción, los if muy simples pueden ponerse sin llaves y el código en la siguiente línea con una tabulación.

   // CON LLAVES
   if(!myNSStringThatIsNil) {
   	myNSStringThatIsNil = @"some text";
   	myNSStringThatIsNil = @"some other text";
   }
   // SIN LLAVES
   if(!myNSStringThatIsNil) 
   	myNSStringThatIsNil = @"just one simple assignment";

• No se deja código innecesario. Una vez realizada las pruebas y estando seguros de como debe quedar, se elimina el código comentado que no aportan valor.

• El código comentado que se considere necesario mantener, contendrá una linea comentada anterior al código que explique qué es y porqué esta comentado.

• En las últimas versiones de xcode ya no hacen falta los @synthesize asi que dejemos de usarlos.

• Como tabulación se usa... una tabulación.

Documentación

• El código va documentado siempre: Clases, métodos y variables, además de las partes de código difíciles de seguir. Se documenta siempre, aunque algunas variables o métodos sean fácilmente identificables, para que no se nos olvide documentar.

• Los comentarios serán siempre en inglés.

• Los comentarios van dirigidos a personas que no hayan hecho ese código. Siendo claro y sin extenderse.

• Clases: Arriba de la linea de declaración del interface va una descripción que explica claramente lo que hace la clase.

• Métodos: Comentados justo arriba de la cabecera, únicamente en la declaración ( en el .h).

• Variables: Comentadas en la linea anterior, con su misma tabulación

• Los TODOs seguirán la siguiente estructura: //TODO: NombreDesarrollador: Comentario_de_lo_que_hay_que_realizar. Nunca se entrega una versión final con TODOs (salvo que sean para versiones futuras) y nunca se deja un TODO sin explicar claramente lo que hay que hacer (y mucho menos en blanco) como si lo fuera a hacer otro. Para que el xcode marque los TODOs o lo que necesiteis poner (yo suelo usar //CACTUS para evitar que salgan en las búsquedas TODOs de librerías o código externo), copiad el siguiente codigo en las build phases del target como nuevo Run script:

   KEYWORDS="CACTUS.|CACTUS:|FIXME:|TODO:|TODO\(|\?\?\?:|\!\!\!:"

find "${SRCROOT}" ( -name ".h" -or -name ".m" ) -print0 | xargs -0 egrep --with-filename --line-number --only-matching "($KEYWORDS).*$" | perl -p -e "s/($KEYWORDS)/ warning: $1/" ```

• En las líneas de comentarios no se usan acentos ni caracteres especiales como la letra Ñ.

Asuntos Técnicos

• El código que generemos estará libre de warnings, tanto de compilación como de análisis (sólo se contemplan aquellos que no podamos quitar porque vengan de librerías externas no desarrolladas por nosotros)
• Refactoriza siempre todo lo que puedas.
• Intenta evitar los métodos con muchas líneas de código. Como regla habitual, si no cabe el método en tu pantalla es que clama al cielo por un refactor.
• Intenta evitar las clases demasiado grandes. Tienden a acumular desidia y mal código. Si una clase crece demasiado, es que se puede refactorizar en clases más pequeñas. Hazlo.
• Intenta evitar más de un nivel de anidamiento. Si lo tienes, puedes extraer lo de dentro del if a un método y tendrás un código más legible.
• Apréndete los atajos de XCode. (http://masteringios.com/blog/2013/12/27/xcode-5-tips-and-tricks/)
• Utiliza siempre el encoding de tus proyectos a UTF-8.

###Guías de estilo de interés

La guía de estilo de Apple y Google aclaran en mayor profundidad algunas buenas prácticas de codificación:

Apple: http://developer.apple.com/library/ios/#documentation/cocoa/conceptual/CodingGuidelines/

Google: http://google-styleguide.googlecode.com/svn/trunk/objcguide.xml

Ray Wenderlich: https://github.com/raywenderlich/objective-c-style-guide/