Вы находитесь на странице: 1из 47

Guías para diseño de aplicaciones y componentes .

NET
Implementando una convención de nombres apropiada

Guías para diseño de


aplicaciones y
componentes .NET
Implementando una convención de
nombres apropiada

Este manual fue creado por TI Capacitación para uso personal de:

Ivan Elias Carrasco Lupinta


rimanace@hotmail.com

1 https://ticapacitacion.com/curso/arquitecturanet
Guías para diseño de aplicaciones y componentes .NET
Implementando una convención de nombres apropiada

Contenido

Acerca del módulo ...............................................................................................................................4


Objetivos ..........................................................................................................................................4
Lección 1 Convenciones sobre el uso de mayúsculas y minúsculas....................................................6
Reglas del uso de mayúsculas y minúsculas para los identificadores ..............................................7
Capitalización de acrónimos.............................................................................................................9
Uso de mayúsculas para palabras compuestas y términos comunes ........................................... 10
Distinción de mayúsculas y minúsculas ........................................................................................ 12
Lección 2 Convenciones generales sobre nombres ......................................................................... 13
Elección de palabras ...................................................................................................................... 14
Uso de abreviaciones y acrónimos ................................................................................................ 16
Evitar los nombres específicos del lenguaje ................................................................................. 17
Nomenclatura de las nuevas versiones de API existentes ............................................................ 19
Lección 3 Nombres de ensamblados, DLLs y espacios de nombres ................................................. 22
Nombres de Ensamblados y DLLs.................................................................................................. 23
Nombres de espacios de nombres ................................................................................................ 25
Conflictos de nombres de tipos y espacios de nombres ............................................................... 27
Lección 4 Nombres de Clases, Estructuras e Interfaces ................................................................... 30
Sustantivos y Adjetivos.................................................................................................................. 31
Nombres de parámetros de tipos genéricos ................................................................................. 33
Nombres de tipos comunes .......................................................................................................... 34
Nomenclatura para enumeraciones ............................................................................................. 35
Lección 5 Nombres de miembros de tipos ........................................................................................ 37
Nombres de métodos.................................................................................................................... 38
Nombres de propiedades .............................................................................................................. 39
Nombres de eventos ..................................................................................................................... 40
Nombres de Campos ..................................................................................................................... 41
Lección 6 Nombres de Parámetros y Recursos ................................................................................. 42

2 https://ticapacitacion.com/curso/arquitecturanet
Este manual fue creado por TI Capacitación para uso personal de:
Ivan Elias Carrasco Lupinta (rimanace@hotmail.com)
Guías para diseño de aplicaciones y componentes .NET
Implementando una convención de nombres apropiada

Nombrando parámetros ............................................................................................................... 43


Nombrando recursos..................................................................................................................... 45

3 https://ticapacitacion.com/curso/arquitecturanet
Este manual fue creado por TI Capacitación para uso personal de:
Ivan Elias Carrasco Lupinta (rimanace@hotmail.com)
Guías para diseño de aplicaciones y componentes .NET
Implementando una convención de nombres apropiada

Acerca del módulo


Seguir un conjunto consistente de convenciones de nomenclatura en el desarrollo de aplicaciones y
componentes .NET puede contribuir a que el código fuente pueda ser fácilmente entendido por otros
desarrolladores o por el mismo desarrollador para ser actualizado posteriormente o incluido en otros
proyectos independientes.

Los nombres de los elementos de código de la aplicación deben ser coherentes, entendibles fácilmente
y transmitir la función que desempeña cada elemento. Una nomenclatura eficiente hace que los
comentarios sobre los elementos de código sean prácticamente nulos.

El objetivo de este módulo es transmitir las recomendaciones de Microsoft para crear un conjunto
consistente de convenciones de nombres que dé como resultado nombres entendibles que tengan un
sentido inmediato para los desarrolladores.

Aunque es recomendable adoptar estas convenciones de nomenclatura como una guía general para
el desarrollo de todo el código, solo se requiere que sean aplicadas a las APIs que son expuestas
públicamente como son los tipos y miembros públicos o protegidos.

En esta guía, la nomenclatura está basada en el lenguaje inglés debido a que cada vez más los equipos
de desarrollo incluyen personas de distintas nacionalidades y con distintos idiomas que deben
compartir código entre sí. En estos escenarios, el lenguaje inglés se ha convertido en el lenguaje más
utilizado a nivel internacional.

El contenido de esta guía está basado en las recomendaciones de Microsoft que podemos encontrar
en el sitio https://docs.microsoft.com/en-us/dotnet/standard/design-guidelines/ plasmadas en una
forma didáctica y fácil de comprender.

Objetivos
Al finalizar este módulo, los participantes contarán con las habilidades y conocimientos para:

• Describir el uso apropiado de minúsculas y mayúsculas.


• Implementar una nomenclatura apropiada para nombres de ensamblados y bibliotecas DLL.
• Implementar una nomenclatura apropiada para espacios de nombres.
• Implementar una nomenclatura apropiada para nombres de clases, estructuras e interfaces.
• Implementar una nomenclatura apropiada para nombres de miembros de un tipo.
• Implementar una nomenclatura apropiada para nombres de parámetros.
• Implementar una nomenclatura apropiada para nombres de recursos.

Las lecciones que forman parte de este módulo son:

• Lección 1: Convenciones sobre el uso de mayúsculas y minúsculas.


• Lección 2: Convenciones generales de nomenclatura.

4 https://ticapacitacion.com/curso/arquitecturanet
Este manual fue creado por TI Capacitación para uso personal de:
Ivan Elias Carrasco Lupinta (rimanace@hotmail.com)
Guías para diseño de aplicaciones y componentes .NET
Implementando una convención de nombres apropiada

• Lección 3: Nombres de ensamblados, bibliotecas DLL y espacios de nombres.


• Lección 4: Nombres de clases, estructuras e interfaces.
• Lección 5: Nombres de miembros de tipos.
• Lección 6: Nombres de parámetros y recursos.

5 https://ticapacitacion.com/curso/arquitecturanet
Este manual fue creado por TI Capacitación para uso personal de:
Ivan Elias Carrasco Lupinta (rimanace@hotmail.com)
Guías para diseño de aplicaciones y componentes .NET
Implementando una convención de nombres apropiada

Lección 1
Convenciones sobre el uso de mayúsculas y
minúsculas
Dado que el CLR soporta distintos lenguajes que podrían o no ser sensibles a mayúsculas y minúsculas,
no es recomendable utilizar una combinación de mayúsculas y minúsculas con el fin de diferenciar
nombres de identificadores. Sin embargo, la importancia del uso de mayúsculas y minúsculas para
mejorar la legibilidad de los nombres no debe ser exagerada. Las guías de esta lección exponen un
método sencillo para el uso de mayúsculas y minúsculas que, cuando se aplica de manera consistente,
hace que los identificadores de tipos, miembros y parámetros sean fáciles de leer.

Objetivos de la lección
Al finalizar esta lección, los participantes podrán:

• Describir las reglas recomendadas de uso apropiado de mayúsculas y minúsculas en los


nombres de identificadores.
• Utilizar apropiadamente la notación PascalCasing y camelCasing.
• Capitalizar apropiadamente acrónimos y palabras compuestas.

6 https://ticapacitacion.com/curso/arquitecturanet
Este manual fue creado por TI Capacitación para uso personal de:
Ivan Elias Carrasco Lupinta (rimanace@hotmail.com)
Guías para diseño de aplicaciones y componentes .NET
Implementando una convención de nombres apropiada

Reglas del uso de mayúsculas y minúsculas para los identificadores


Para diferenciar las palabras en un identificador, se recomienda poner en mayúscula (capitalizar) la
primera letra de cada palabra en el identificador. En el idioma inglés, el término común utilizado para
poner en mayúscula una letra es conocido como Capitalización (Capitalization). No se recomienda
utilizar guion bajo en ningún lugar en los identificadores para diferenciar palabras. Hay dos formas
apropiadas para capitalizar identificadores dependiendo de su uso:

• PascalCasing
• camelCasing

Se recomienda utilizar la convención PascalCasing para todos los identificadores, excepto para los
nombres de parámetros. La convención PascalCasing consiste en escribir en mayúscula el primer
carácter de cada palabra, incluyendo los acrónimos con más de dos letras de longitud, tal como se
muestra en los ejemplos siguientes:

ProductName
MvcHtmlString

Un caso especial es el de acrónimos con dos letras en los que ambas letras con capitalizadas como se
muestra en los siguientes identificadores:

System.IO
IOStream

Se recomienda utilizar la convención camelCasing únicamente para los nombres de los parámetros. La
convención camelCasing consiste en escribir en mayúscula la primera letra de cada palabra excepto
en la primera palabra.

productName
connectionString
mvcHtmlString

Como se muestra en el siguiente ejemplo, los acrónimos de dos letras al inicio de un identificador
deben escribirse en minúsculas.

ioStream

Las siguientes son dos guías básicas de capitalización para identificadores:

✓ Utilizar PascalCasing para espacios de nombres, tipos y nombres de miembros consistentes de


múltiples palabras.

Por ejemplo, utilizar TextColor en lugar de Textcolor o Text_color.

7 https://ticapacitacion.com/curso/arquitecturanet
Este manual fue creado por TI Capacitación para uso personal de:
Ivan Elias Carrasco Lupinta (rimanace@hotmail.com)
Guías para diseño de aplicaciones y componentes .NET
Implementando una convención de nombres apropiada

Palabras simples como Button tienen simplemente una letra capital al inicio.

Palabras compuestas que son escritas siempre como una sola palabra, por ejemplo, “endpoint”
son tratadas como palabras simples y tienen letra capital inicial solamente: Endpoint.

✓ Utilizar camelCasing para los nombres de parámetros.

La siguiente tabla describe la regla de capitalización para diferentes tipos de identificadores.

Identificador Convención Ejemplo


Espacio de nombres Pascal namespace NorthWind { . . . }
namespace NorthWind.Dal { . . . }
Tipo Pascal public class Program { . . . }
public class NorthWindRepository { . . . }
Interface Pascal public interface IDisposable
public interface IRepository
Método Pascal static void Main(string[] args)
public Product GetProductByID()
Propiedad Pascal public int ProductId { get; set; }
Evento Pascal public event EventHandler Exited
Campo Pascal public const float PI = 3.14159f
private string ProductName
Valor en una enumeración Pascal public enum Days
{
Monday, Sunday
}
Parámetros Camel static void Main(string[] args)
public Product GetProductByID(string id)

8 https://ticapacitacion.com/curso/arquitecturanet
Este manual fue creado por TI Capacitación para uso personal de:
Ivan Elias Carrasco Lupinta (rimanace@hotmail.com)
Guías para diseño de aplicaciones y componentes .NET
Implementando una convención de nombres apropiada

Capitalización de acrónimos
Como regla general es importante evitar el uso de acrónimos en los nombres de identificadores a
menos que esos acrónimos sean de uso común y sean entendibles inmediatamente por cualquier
persona que los utilice. Por ejemplo, JSON, HTML, XML o IO son acrónimos bastante conocidos. Los
acrónimos poco conocidos deben evitarse definitivamente.

Los acrónimos son distintos de las abreviaciones las cuales nunca deben ser utilizadas en
identificadores. Un acrónimo es una palabra formada por las letras iniciales de una frase mientras que
una abreviación simplemente acorta una palabra.

Por definición, un acrónimo debe ser de al menos 2 caracteres. Los acrónimos de 3 o más caracteres
siguen las guías de cualquier otra palabra donde únicamente la primera letra es capitalizada al menos
que sea la primera palabra del nombre de un parámetro en cuyo caso todos los caracteres son en
minúsculas.

Los siguiente son algunos ejemplos de uso de acrónimos en identificadores:

public void StartIO(Stream ioStream, bool closeIOStream){ . . . }


public void ProcessHtmlTag(string htmlTag) { . . . }

Recomendaciones:

✓ Capitalizar los caracteres de un acrónimo de 2 caracteres excepto cuando sea la primera


palabra de un identificador en camelCasing.

System.IO
public void StartIO(Stream ioStream)

✓ Capitalizar solamente el primer carácter de los acrónimos de 3 o mas caracteres, excepto


cuando sea la primera palabra de un identificador camelCasing.

System.Xml
public void ProcessXmlTag(string xmlTag)

✓ No capitalizar los caracteres de cualquier acrónimo al inicio de un identificador camelCasing


independientemente de su longitud.

9 https://ticapacitacion.com/curso/arquitecturanet
Este manual fue creado por TI Capacitación para uso personal de:
Ivan Elias Carrasco Lupinta (rimanace@hotmail.com)
Guías para diseño de aplicaciones y componentes .NET
Implementando una convención de nombres apropiada

Uso de mayúsculas para palabras compuestas y términos comunes


Las palabras compuestas son aquellas palabras que se forman a partir de la unión de dos o más
palabras simples.

Las palabras compuestas se pueden formar de 3 maneras:

• Forma abierta. Escritas como 2 o más palabras separadas por espacio. Ejemplos:

Español: Coche cama, ex primera dama


Inglés: Bit Flag, Ice Cream, File Name

• Forma cerrada. Se unen para formar una simple palabra. Ejemplos:

Español: Abrelatas, lanzallamas


Inglés: Callback, Keyboard, Software, Endpoint

• Forma semicerrada. 2 palabras unidas por un guion. Ejemplos:

Español: Norte-Sur, Ítalo-Frances


Inglés: x-ray, long-term, well-known

Muchos de los términos compuestos son tratados como una sola palabra para propósito de
capitalización.

Recomendación:

 No capitalizar cada palabra en los tipos de palabras compuestas cerradas, por ejemplo, la
palabra compuesta Endpoint.

Para el propósito de la guía de uso apropiado de mayúsculas y minúsculas, se recomienda tratar a las
palabras compuestas cerradas como una sola palabra. De ser necesario, puede consultarse un
diccionario para determinar si una palabra se escribe de forma cerrada.

La siguiente tabla muestra la capitalización para algunas de las palabras y términos compuestos más
comunes.

Pascal Camel No
BitFlag bitFlag Bitflag
Callback callback CallBack
Canceled canceled Cancelled
DoNot doNot Don´t
Email email EMail
Endpoint endpoint EndPoint
FileName fileName Filename

10 https://ticapacitacion.com/curso/arquitecturanet
Este manual fue creado por TI Capacitación para uso personal de:
Ivan Elias Carrasco Lupinta (rimanace@hotmail.com)
Guías para diseño de aplicaciones y componentes .NET
Implementando una convención de nombres apropiada

Gridline gridline GridLine


Hashtable hashtable HashTable
Id id ID
Indexes indexes Indices
LogOff logOff LogOut
LogOn logOn LogIn
Metadata metadata MetaData, metaData
Multipanel multipanel MultiPanel
Multiview multiview MultiView
Namespace namespace NameSpace
Ok ok OK
Pi pi PI
Placeholder placeholder PlaceHolder
SignIn signIn SignOn
SignOut signOut SignOff
UserName userName Username
WhiteSpace whiteSpace Whitespace
Writable writable Writeable

Dos términos de uso común (Id y Ok) son excepciones a la recomendación de no utilizar abreviaciones
en los nombres de los identificadores. La razón de esto es que ambos términos son abreviaturas de
uso común.

11 https://ticapacitacion.com/curso/arquitecturanet
Este manual fue creado por TI Capacitación para uso personal de:
Ivan Elias Carrasco Lupinta (rimanace@hotmail.com)
Guías para diseño de aplicaciones y componentes .NET
Implementando una convención de nombres apropiada

Distinción de mayúsculas y minúsculas


A los lenguajes que permiten generar código para ser ejecutado en el CLR no les es requerido soportar
la sensibilidad al uso de mayúsculas y minúsculas, aunque algunos de ellos lo hacen, como el caso de
C#.

Aunque el lenguaje que utilicemos soporte la sensibilidad al uso de mayúsculas y minúsculas, otros
lenguajes que podrían tener acceso a nuestro código podrían no hacerlo. Cualquier API que sea
accesible externamente, por lo tanto, no puede confiar solo por la diferencia entre mayúsculas y
minúsculas para distinguir entre dos nombres en el mismo contexto.

Recomendación:

 No hay que asumir que todos los lenguajes de programación distinguen entre mayúsculas y
minúsculas. No es así. Los nombres de identificadores no pueden diferenciarse solo por el uso
de mayúsculas y minúsculas.

12 https://ticapacitacion.com/curso/arquitecturanet
Este manual fue creado por TI Capacitación para uso personal de:
Ivan Elias Carrasco Lupinta (rimanace@hotmail.com)
Guías para diseño de aplicaciones y componentes .NET
Implementando una convención de nombres apropiada

Lección 2
Convenciones generales sobre nombres
Esta lección describe las convenciones generales de nomenclatura que se relacionan con la elección
de palabras, directrices sobre el uso de abreviaturas y acrónimos, así como recomendaciones de cómo
evitar el uso de nombres específicos del lenguaje.

Objetivos de la lección
Al finalizar esta lección, los participantes podrán:

• Elegir palabras apropiadas para los nombres de identificadores.


• Identificar los casos de uso de acrónimos y abreviaciones.
• Entender la importancia de evitar el uso de nombres específicos del lenguaje para los nombres
de identificadores.
• Utilizar nombres apropiados para versiones nuevas de APIs existentes.

13 https://ticapacitacion.com/curso/arquitecturanet
Este manual fue creado por TI Capacitación para uso personal de:
Ivan Elias Carrasco Lupinta (rimanace@hotmail.com)
Guías para diseño de aplicaciones y componentes .NET
Implementando una convención de nombres apropiada

Elección de palabras
Es importante que los nombres de los identificadores hagan sentido en la primera lectura. Los nombres
de los identificadores deben informar claramente lo que cada miembro hace y lo que representa cada
tipo y parámetro. Con este fin, es más importante que el nombre sea más claro en lugar de ser más
corto. Los nombres deben corresponder a escenarios del sistema en lugar de utilizar nombres que se
refieran a tecnologías o arquitectura.

Recomendaciones:

✓ Elegir nombres para los identificadores que puedan ser leídos fácilmente.

Por ejemplo, en inglés, un nombre de propiedad HorizontalAlignment es más legible que el


nombre de propiedad AlignmentHorizontal.

✓ Preferir la legibilidad sobre la brevedad en los nombres.

Por ejemplo, un nombre de propiedad CanScrollHorizontally es mejor que ScrollableX.

 No utilizar guion bajo, guion medio o cualquier otro carácter no alfanumérico.

 No utilizar la notación Húngara.

La convención de notación Húngara especifica el uso en minúsculas de un prefijo para el


nombre del identificador que indique el tipo de datos que representa. Por ejemplo, la variable
intCount podría representar un número entero. El problema con la notación Húngara es que
al cambiar el tipo de la variable requerirá cambiar también el nombre de la variable en todos
los lugares que sea utilizado.

 Evitar el uso de identificadores que hagan conflicto con palabras clave utilizadas ampliamente
en los lenguajes de programación.

De acuerdo a la Regla 4 de la Especificación de Lenguaje Común (Common Language


Specification o CLS), todos los lenguajes compatibles deben proporcionar un mecanismo que
permita el acceso a los elementos con nombre que utilicen una palabra clave de ese lenguaje
como identificador. C#, por ejemplo, usa el carácter @ como un mecanismo de escape en este
caso. Sin embargo, es una buena idea evitar palabras clave comunes porque es mucho más
difícil utilizar un método que tenga la secuencia de escape que uno sin él.

El siguiente ejemplo muestra el uso de identificadores que utilizan nombres de palabra clave
en C#.

class Program
{

14 https://ticapacitacion.com/curso/arquitecturanet
Este manual fue creado por TI Capacitación para uso personal de:
Ivan Elias Carrasco Lupinta (rimanace@hotmail.com)
Guías para diseño de aplicaciones y componentes .NET
Implementando una convención de nombres apropiada

static void Main(string[] args)


{
@if();

static void @if()


{
Console.WriteLine("Hello, World!");
}

15 https://ticapacitacion.com/curso/arquitecturanet
Este manual fue creado por TI Capacitación para uso personal de:
Ivan Elias Carrasco Lupinta (rimanace@hotmail.com)
Guías para diseño de aplicaciones y componentes .NET
Implementando una convención de nombres apropiada

Uso de abreviaciones y acrónimos


En general, no es recomendable el uso de abreviaciones o acrónimos en identificadores. Como
comentamos previamente, es más importante el uso de nombres legibles en lugar del uso de nombres
cortos. Es igual de importante no utilizar abreviaciones o acrónimos que no sean muy conocidos, esto
es, no debemos utilizar algo que la mayoría de la gente no experta en una cierta área no pueda
reconocer su significado inmediatamente.

Recomendaciones:

 No utilizar abreviaciones o contracciones como parte de los nombres de los identificadores.

Por ejemplo, utilizar GetProduct en lugar de GetProd.

 No utilizar acrónimos que no sean ampliamente aceptados e incluso, si lo son, utilizarlos solo
cuando sea necesario.

Por ejemplo, UI es utilizado como acrónimo de User Interface y HTML es utilizado como
acrónimo de Hyper Text Markup Language.

16 https://ticapacitacion.com/curso/arquitecturanet
Este manual fue creado por TI Capacitación para uso personal de:
Ivan Elias Carrasco Lupinta (rimanace@hotmail.com)
Guías para diseño de aplicaciones y componentes .NET
Implementando una convención de nombres apropiada

Evitar los nombres específicos del lenguaje


Los lenguajes de programación destinados al CLR frecuentemente tienen sus propios nombres o alias
para los tipos primitivos. Por ejemplo, int es el alias de C# para System.Int32.

Para asegurar que nuestro código pueda tomar ventaja completa de la interoperabilidad entre
lenguajes que es una característica del CLR, es importante evitar el uso de esos nombres de tipo
específicos del lenguaje en los nombres de identificadores.

Recomendaciones:

✓ Utilizar nombres con interés semántico en lugar de las palabras clave de los nombres de tipo
específicos del lenguaje.

Por ejemplo, para nombrar un método que devuelve el valor de la longitud de una figura es
preferible utilizar GetLength en lugar de GetInt.

Otro ejemplo es el caso cuando el código será utilizado por otros lenguajes. En este caso es
preferible utilizar el método GetNoValue en lugar de GetNullValue. C# utiliza null, pero Visual
Basic utiliza Nothing.

✓ Utilizar un nombre de tipo del CLR en lugar de un nombre especifico del lenguaje para los casos
raros donde un identificador no tiene un significado semántico más allá de su tipo.

Por ejemplo, un método que convierte un valor a un tipo System.Int64 debería ser llamado
ToInt64, no ToLong debido a que System.Int64 es el nombre CLR para el alias long especifico
de C#.

La siguiente tabla muestra varios tipos de datos base utilizando los nombres de tipo CLR, así
como los nombres del tipo que corresponden para C#, Visual Basic y C++.

C# Visual Basic C++ CLR


sbyte SByte char SByte
byte Byte unsigned char Byte

short Short short Int16


ushort UInt16 unsigned short UInt16

int Integer int Int32


uint UInt32 unsigned int UInt32

long Long __int64 Int64


ulong UInt64 unsigned __int64 UInt64

17 https://ticapacitacion.com/curso/arquitecturanet
Este manual fue creado por TI Capacitación para uso personal de:
Ivan Elias Carrasco Lupinta (rimanace@hotmail.com)
Guías para diseño de aplicaciones y componentes .NET
Implementando una convención de nombres apropiada

float Single float Single


double Double double Double
bool Boolean bool Boolean
char Char wchar_t Char
string String String String
object Object Object Object

✓ Utilizar un nombre común, tal como value o ítem, en lugar de repetir el nombre del tipo en los
casos raros donde un identificador no tiene un significado semántico y el tipo del parámetro
no sea importante.

Los siguientes nombres de métodos de una clase que soporta el procesamiento de varios tipos
de datos es un ejemplo de esta recomendación.

void Add(double value){ . . }

void Add(int value){ . . }

void Add(float value){ . . }

Los ejemplos anteriores son preferibles en lugar de los siguientes:

void Add(double doubleValue){ . . }

void Add(int intValue){ . . }

void Add(float floatValue){ . . }

18 https://ticapacitacion.com/curso/arquitecturanet
Este manual fue creado por TI Capacitación para uso personal de:
Ivan Elias Carrasco Lupinta (rimanace@hotmail.com)
Guías para diseño de aplicaciones y componentes .NET
Implementando una convención de nombres apropiada

Nomenclatura de las nuevas versiones de API existentes


Algunas veces una nueva característica no puede ser agregada a un tipo existente, aunque el nombre
del tipo implique que es el mejor lugar para la nueva característica. En tal caso, un nuevo tipo necesita
ser agregado y surge la difícil tarea de encontrar un nuevo nombre para el nuevo tipo. De manera
similar, frecuentemente un miembro existente no puede ser extendido o sobrecargado para
proporcionar funcionalidad adicional y, por lo tanto, un miembro con un nuevo nombre necesita ser
agregado.

Las siguientes guías ayudan a elegir los nombres para los nuevos tipos y miembros que toman el lugar
o remplazan tipos o miembros existentes.

✓ Utilizar un nombre similar al de la API anterior al crear nuevas versiones de una API existente.

Esto ayuda a resaltar la relación entre las APIs como se muestra en el siguiente ejemplo.

class NorthWind
{
[Obsolete(
"SetConnectionString has been deprecated. Please use
NorthWindSetup.ConnectionString instead.")]
public void SetConnectionString(string connectionString) {}
}

class NorthWindSetup
{
public string ConnectionString { get; set; }
}

✓ Preferir agregar un sufijo en lugar de un prefijo para indicar una nueva versión de una API
existente.

Esto ayudará a encontrar la nueva versión de la API al navegar por la documentación o al


utilizar el IntelliSense. La versión anterior de la API estará organizada cerca de la nueva API
debido a que la mayoría de los exploradores y el IntelliSense muestran los identificadores en
orden alfabético.

Un ejemplo de esto lo podemos ver en la clase ReaderWriterLockSlim que representa una


versión más rápida de la clase ReaderWriterLock. El equipo de desarrollo de Microsoft debatió
en que si el nombre debería ser SlimReaderWriterLock siguiendo la recomendación de que se
debe escribir tal y como se pronuncia en inglés, sin embargo, decidieron que la capacidad de
ser encontrada fácilmente era lo más importante tal y como se muestra en la siguiente imagen.

19 https://ticapacitacion.com/curso/arquitecturanet
Este manual fue creado por TI Capacitación para uso personal de:
Ivan Elias Carrasco Lupinta (rimanace@hotmail.com)
Guías para diseño de aplicaciones y componentes .NET
Implementando una convención de nombres apropiada

✓ Considerar el uso de un nuevo nombre significativo de identificador en lugar de solo agregar


un prefijo o sufijo.

✓ Utilizar un sufijo numérico para indicar una nueva versión de una API existente,
particularmente si el nombre existente de la API es el único nombre que hace sentido, esto es,
si es un estándar del sector y que el agregar cualquier sufijo significativo o cambiar el nombre
no es una opción apropiada. Un ejemplo de este caso lo tenemos en la clase X509Certificate y
su versión posterior X509Certificate2.

Una recomendación importante sobre este punto es el de utilizar el sufijo numérico como
último recurso.

Como nota curiosa, cuando Microsoft liberó un nuevo tipo de datos llamado TimeZone2, este
nombre se volvió un centro de controversia en la comunidad de desarrolladores. Después de
varias discusiones, el equipo de desarrollo decidió renombrar ese tipo por TimeZoneInfo. Lo
curioso de este asunto es que nadie mostró un desacuerdo por el nombre X509Certificate2,
llegando a la conclusión de que los programadores son más complacientes de aceptar el sufijo
numérico en los tipos de bibliotecas raramente utilizados.

✓ Utilizar el sufijo "64" al introducir las versiones de API que operen en enteros de 64 bits (un
entero largo) en lugar de un entero de 32 bits.

Solo se debe adoptar este enfoque cuando la API de 32 bits exista; no es necesario hacerlo
para la nuevas APIs con únicamente una versión de 64 bits.

20 https://ticapacitacion.com/curso/arquitecturanet
Este manual fue creado por TI Capacitación para uso personal de:
Ivan Elias Carrasco Lupinta (rimanace@hotmail.com)
Guías para diseño de aplicaciones y componentes .NET
Implementando una convención de nombres apropiada

Por ejemplo, varias APIs en la clase System.Diagnostics.Process devuelven valores Int32


representando valores de memoria, tal como PagedMemorySize o PagedSystemMemorySize.
Para soportar apropiadamente estas APIs en sistemas de 64 bits, se agregaron APIs con el
mismo nombre, pero con sufijo 64.

Es importante mencionar que esta guía aplica solo a versiones nuevas de APIs existentes.
Cuando se diseña una nueva API, se recomienda utilizar tipos y nombres apropiados que
trabajen en todas las plataformas evitando el uso de los sufijos “32” y “64”.

 No utilizar el sufijo “Ex” o uno similar para indicar que la API fue “EXtendida” y distinguirla de
una versión anterior de la misma API.

El siguiente ejemplo muestra algunas opciones de nombres para una nueva API de Employee.

// API
public class Employee { }

// Nueva API
public class EmployeeEx { } // No recomendado
public class EmployeeNew { } // No recomendado
public class Employee2 { } // Recomendado como último recurso
public class Manager { } // Recomendado

21 https://ticapacitacion.com/curso/arquitecturanet
Este manual fue creado por TI Capacitación para uso personal de:
Ivan Elias Carrasco Lupinta (rimanace@hotmail.com)
Guías para diseño de aplicaciones y componentes .NET
Implementando una convención de nombres apropiada

Lección 3
Nombres de ensamblados, DLLs y espacios de nombres
En esta lección se describen las convenciones de nomenclatura para ensamblados, DLLs y espacios de
nombres. Se describe también la forma de evitar conflictos de nombres similares de tipos que residen
en espacios de nombres distintos.

Objetivos de la lección
Al finalizar esta lección, los participantes podrán:

• Describir la nomenclatura recomendada para nombrar ensamblados y DLLs.


• Describir la nomenclatura para nombrar espacios de nombres.
• Identificar los conflictos de nombres de tipos similares en espacios de nombres distintos.

22 https://ticapacitacion.com/curso/arquitecturanet
Este manual fue creado por TI Capacitación para uso personal de:
Ivan Elias Carrasco Lupinta (rimanace@hotmail.com)
Guías para diseño de aplicaciones y componentes .NET
Implementando una convención de nombres apropiada

Nombres de Ensamblados y DLLs


Un ensamblado es la unidad de implementación y la identidad para los programas de código
administrado. Aunque los ensamblados pueden abarcar uno o varios archivos, típicamente un
ensamblado es mapeado uno-a-uno con un DLL. Por lo tanto, será suficiente describir únicamente las
convenciones de nomenclatura para DLLs ya que estas convenciones pueden ser mapeadas a las
convenciones de nomenclatura para los ensamblados.

Visual Studio no tiene soporte para crear ensamblados que abarquen múltiples archivos.
Si deseamos crear ensamblados que abarquen múltiples archivos, debemos utilizar
herramientas de línea de comandos.

El siguiente enlace contiene información con los pasos para crear ensamblados de
múltiples archivos.

How to: Build a Multifile Assembly


https://docs.microsoft.com/en-us/dotnet/framework/app-domains/how-to-build-a-
multifile-assembly

Es importante tomar en cuenta que los espacios de nombres (namespaces) son distintos de los
nombres de ensamblados y DLLs. Namespaces representan agrupamientos lógicos para los
desarrolladores mientras que los DLLs y ensamblados representan límites de empaquetado e
implementación. Los DLLs pueden contener múltiples Namespaces. Si decidimos utilizar
MyCompany.MyTechnology como nombre del DLL, esto no implica que el DLL debe contener un
espacio de nombres llamado MyCompany.MyTechnology aunque asi puede ser.

Recomendaciones:

✓ Elegir nombres para DLLs de ensamblados que sugieran grandes fragmentos de funcionalidad
tal como System.Data.

Los nombres de ensamblados y DLLs no tienen que corresponder a los nombres de


Namespaces, pero es razonable seguir el nombre del Namespace al nombrar los ensamblados.
Una buena regla de oro es nombrar al DLL basándose en el prefijo común de los espacios de
nombre contenidos en el ensamblado. Por ejemplo, un ensamblado con los espacios de
nombre:

MyCompany.MyTechnology.FirstFeature
MyCompany.MyTechnology.SecondFeature

23 https://ticapacitacion.com/curso/arquitecturanet
Este manual fue creado por TI Capacitación para uso personal de:
Ivan Elias Carrasco Lupinta (rimanace@hotmail.com)
Guías para diseño de aplicaciones y componentes .NET
Implementando una convención de nombres apropiada

podría ser llamado MyCompany.MyTechnology.dll.

✓ Considerar nombrar los DLLs de acuerdo al siguiente patrón:

<Empresa>.<Componente>.dll

donde <Componente> contiene una o más clausulas separadas por un punto. Por ejemplo:

Microsoft.EntityFrameworkCore.dll
Microsoft.EntityFrameworkCore.Relational.dll

24 https://ticapacitacion.com/curso/arquitecturanet
Este manual fue creado por TI Capacitación para uso personal de:
Ivan Elias Carrasco Lupinta (rimanace@hotmail.com)
Guías para diseño de aplicaciones y componentes .NET
Implementando una convención de nombres apropiada

Nombres de espacios de nombres


Como en otras directrices de nomenclatura, el objetivo al asignar nombres a los Namespaces es el de
crear una mayor claridad suficiente para que los programadores que utilizan nuestros componentes
puedan saber inmediatamente lo que probablemente contenga el espacio de nombres.

La siguiente plantilla especifica la regla general para nombrar a los Namespaces:

<Empresa>.<Producto o tecnología>[.<Característica>][.<Subespacio de nombres>]

Por ejemplo:

Microsoft.VisualStudio
Microsoft.VisualStudio.Design
Contoso.Math
NorthWind.Security

Recomendaciones:

✓ Utilizar prefijos de espacios de nombres con el nombre de compañía para evitar que los
espacios de nombres de diferentes compañías tengan el mismo nombre.

Por ejemplo, las APIs de automatización de Microsoft Office proporcionadas por Microsoft
deben estar en el espacio de nombres Microsoft.Office.

Es importante utilizar el nombre oficial de la empresa u organización al seleccionar la primera


parte del nombre del Namespace para evitar posibles conflictos. Por ejemplo, si Microsoft
hubiera decidido utilizar MS como la raíz de su Namespace, esto podría generar un conflicto
para los desarrolladores de otra empresa que utilicen la abreviación MS.

✓ Utilizar un nombre de producto estable independiente de la versión en el segundo nivel del


nombre del Namespace.

 No utilizar jerarquías organizacionales como base para los nombres en las jerarquías de
espacio de nombres debido a que los nombres de grupo dentro de las organizaciones tienden
a ser de corta duración. Es preferible organizar la jerarquía de espacios de nombres en torno
a grupos de tecnologías relacionadas.

✓ Utilizar PascalCasing y separar los componentes del espacio de nombres con un punto, por
ejemplo, Microsoft.Office.PowerPoint. Si la empresa utiliza una notación de mayúsculas y
minúsculas no tradicional, debemos seguir la notación definida por la empresa, incluso si se
desvía de la notación PascalCasing sugerida.

✓ Considerar el uso de nombres en plural para los espacios de nombres cuando sea apropiado.
25 https://ticapacitacion.com/curso/arquitecturanet
Este manual fue creado por TI Capacitación para uso personal de:
Ivan Elias Carrasco Lupinta (rimanace@hotmail.com)
Guías para diseño de aplicaciones y componentes .NET
Implementando una convención de nombres apropiada

Por ejemplo, utilizar System.Collections en lugar de System.Collection. Los nombres de marcas


y acrónimos son excepciones a esta regla. Por ejemplo, se recomienda utilizar System.IO en
lugar de System.IOs.

 No utilizar el mismo nombre para un espacio de nombres y un tipo en ese espacio de nombres.

Por ejemplo, no utilizar NorthWind como un nombre para un Namespace y después agregar
también una clase llamada NorthWind en ese espacio de nombres. Diversos compiladores
requieren que tales tipos estén completamente cualificados.

26 https://ticapacitacion.com/curso/arquitecturanet
Este manual fue creado por TI Capacitación para uso personal de:
Ivan Elias Carrasco Lupinta (rimanace@hotmail.com)
Guías para diseño de aplicaciones y componentes .NET
Implementando una convención de nombres apropiada

Conflictos de nombres de tipos y espacios de nombres


Los espacios de nombres son utilizados para organizar tipos dentro de una jerarquía lógica y fácil de
explorar. También son indispensables para resolver ambigüedades de nombres de tipos que podrían
surgir cuando importamos múltiples espacios de nombres. Sin embargo, ese hecho no debe ser
utilizado como una excusa para introducir ambigüedades conocidas entre tipos de diferentes espacios
de nombres que comúnmente sean utilizados juntos. En escenarios comunes, no se le debe requerir
al desarrollador cualificar los nombres de tipos, esto es, no se le debe requerir que especifique
explícitamente el espacio de nombres de los tipos utilizados.

Recomendaciones:

 No utilizar nombres de tipos comunes como Element, Node, Log y Message.

Hay una probabilidad muy alta de que, al hacerlo, dará lugar a que el nombre del tipo entre en
conflicto en escenarios comunes. Debemos cualificar el nombre común de un tipo, por
ejemplo: FormElement, XmlNode, EventLog, SoapMessage.

Existen guías especificas para evitar conflictos de nombres de tipos para las diferentes
categorías de espacios de nombres. Los espacios de nombres pueden ser divididos en las
siguientes categorías:

• Espacios de nombres de modelo de aplicación.

• Espacios de nombres de Infraestructura.


• Espacios de nombres Núcleo.

• Grupos de espacios de nombres de tecnología.

Espacios de nombres de modelo de aplicación

Los espacios de nombres que pertenecen a un único modelo de aplicación frecuentemente


son utilizados juntos y casi nunca son utilizados con espacios de nombres de otros modelos
de aplicación. Por ejemplo, el espacio de nombres System.Windows.Forms muy rara vez es
utilizado junto con el espacio de nombres System.Web.UI.

Recomendación:

 No proporcionar el mismo nombre para tipos en espacios de nombre dentro de un


solo modelo de aplicación.

27 https://ticapacitacion.com/curso/arquitecturanet
Este manual fue creado por TI Capacitación para uso personal de:
Ivan Elias Carrasco Lupinta (rimanace@hotmail.com)
Guías para diseño de aplicaciones y componentes .NET
Implementando una convención de nombres apropiada

Por ejemplo, no agregar un tipo llamado Product al espacio de nombres


NorthWind.Dal.Accounting si el espacio de nombres NorthWind.Dal ya contiene un
tipo llamado Product.

Espacio de nombres de Infraestructura

Este grupo contiene los espacios de nombres que rara vez son importados durante el
desarrollo de aplicaciones comunes. Por ejemplo, los espacios de nombres .Design son
utilizados principalmente cuando se desarrollan herramientas de programación. Evitar
conflictos con los tipos pertenecientes a estos espacios de nombres no es crítico.

System.Windows.Forms.Design y Microsoft.EntityFrameworkCore.Design son un ejemplo de


espacios de nombres de infraestructura.

Espacio de nombres núcleo

Los espacios de nombres núcleo incluyen todos los espacios de nombres System, excluyendo
los espacios de nombres de los modelos de aplicaciones y los espacios de nombres de
infraestructura. Los espacios de nombres núcleo incluyen entre otros a System, System.IO,
System.Xml y System.Net.

Recomendación:

 No elegir nombres de tipos que podrían entrar en conflicto con cualquier otro tipo
dentro de los espacios de nombres núcleo.

Por ejemplo, no utilizar Stream como nombre para un tipo ya que podría entrar en
conflicto con el tipo System.IO.Stream que es un tipo que se utiliza comúnmente.

Grupos de espacios de nombres de tecnología

Esta categoría incluye todos los espacios de nombres en los cuales los dos primeros nodos son
iguales (<Empresa>.<Tecnología>*), por ejemplo Microsoft.EntityFrameworkCore.Relational
y Microsoft.EntityFrameworkCore.SqlServer. Es importante que los tipos que pertenecen a la
misma tecnología no entren en conflicto entre sí.

Recomendaciones:

 No asignar nombres de tipos que podrían entrar en conflicto con otros tipos dentro de
la misma tecnología.

 No introducir conflictos por nombres de tipos entre tipos en espacios de nombre de


tecnología y un espacio de nombres de modelo de aplicación a menos que no se
intente utilizar la tecnología con el modelo de aplicación.

28 https://ticapacitacion.com/curso/arquitecturanet
Este manual fue creado por TI Capacitación para uso personal de:
Ivan Elias Carrasco Lupinta (rimanace@hotmail.com)
Guías para diseño de aplicaciones y componentes .NET
Implementando una convención de nombres apropiada

Por ejemplo, no debe agregarse un tipo llamado Binding al espacio de nombres


Microsoft.EntityFrameworkCore si el espacio de nombres System.Windows.Data ya
contiene ese nombre de tipo.

29 https://ticapacitacion.com/curso/arquitecturanet
Este manual fue creado por TI Capacitación para uso personal de:
Ivan Elias Carrasco Lupinta (rimanace@hotmail.com)
Guías para diseño de aplicaciones y componentes .NET
Implementando una convención de nombres apropiada

Lección 4
Nombres de Clases, Estructuras e Interfaces
En esta lección se describen las recomendaciones para la nomenclatura de Clases, Estructuras e
Interfaces. Se describe también la nomenclatura para los parámetros de tipo en los tipos genéricos
personalizados y las enumeraciones.

Esta lección presenta también la nomenclatura sugerida para nombrar tipos personalizados que
derivan o implementan tipos existentes en las implementaciones .NET tal como el .NET Framework o
.NET Core.

Objetivos de la lección
Al finalizar esta lección, los participantes podrán:

• Seleccionar el nombre apropiado para Clases, Estructuras, Interfaces y Enumeraciones.


• Seleccionar el nombre apropiado para los parámetros de tipo.
• Seleccionar nombres apropiados para tipos que derivan o implementan tipos predefinidos.

30 https://ticapacitacion.com/curso/arquitecturanet
Este manual fue creado por TI Capacitación para uso personal de:
Ivan Elias Carrasco Lupinta (rimanace@hotmail.com)
Guías para diseño de aplicaciones y componentes .NET
Implementando una convención de nombres apropiada

Sustantivos y Adjetivos
En general, los nombres de clases y estructuras deberían ser sustantivos como Repository o frases
nominales como ProductRepository debido a que representan entidades del sistema. Una regla de oro
es que si no somos capaces de encontrar un sustantivo o frase nominal para el nombre de una clase o
estructura probablemente deberíamos repensar el diseño general del tipo.

Las interfaces representando la raíz de una jerarquía como por ejemplo IList<T> deben también utilizar
sustantivos o frases nominales.

Las interfaces representando capacidades deben utilizar adjetivos como IComparable<T> o frases
adjetivas como IBindableProduct.

Otra consideración importante es que para los tipos que son comúnmente más utilizados, deben
utilizarse los nombres que sean reconocibles más fácilmente aun si el nombre es más apropiado para
algún otro tipo menos utilizado.

Por ejemplo, un tipo utilizado principalmente en escenarios para enviar trabajos a colas de impresión
debería ser llamado Printer en lugar de PrintQueue. Aunque técnicamente el tipo representa una cola
de impresión y no el dispositivo físico, desde el punto de vista del escenario, Printer es el nombre ideal
debido a que mucha gente esta interesada en enviar trabajos de impresión y no en otras operaciones
relacionadas con el dispositivo físico, por ejemplo, para configurar la impresora.

Si necesitamos proporcionar otro tipo que corresponda por ejemplo a la impresora física para ser
utilizada en escenarios de configuración, el tipo podría ser llamado PrinterConfiguration o
PrinterManager.

Recomendaciones:

✓ Nombrar las clases y estructuras con sustantivos o frases nominales utilizando la notación
PascalCasing.

Esto hace una distinción entre los nombres de tipos y los nombres de métodos, estos últimos
son nombrados utilizando verbos.

✓ Nombrar las interfaces con adjetivos, frases adjetivas u ocasionalmente con sustantivos o
frases nominales.

Los nombres y frases nominales rara vez deben ser utilizados ya que esto podría ser un
indicador de que el tipo debería ser una clase abstracta y no una interface.

 No utilizar el prefijo “C” en los nombres de clases.

✓ Considerar la finalización del nombre de las clases derivadas con el nombre de la clase base.

31 https://ticapacitacion.com/curso/arquitecturanet
Este manual fue creado por TI Capacitación para uso personal de:
Ivan Elias Carrasco Lupinta (rimanace@hotmail.com)
Guías para diseño de aplicaciones y componentes .NET
Implementando una convención de nombres apropiada

Esto es muy legible y explica claramente la relación entre las clases. Un ejemplo de esto es
ArgumentOutOfRangeException que es un tipo derivado de Exception. Otro ejemplo es
SerializableAttribute que es un tipo derivado de Attribute.

Es importante utilizar un juicio razonable al aplicar esta recomendación ya que algunas veces
utilizar el sufijo no aporta demasiada información, por ejemplo, la clase Button es un nombre
de tipo completamente válido que deriva de la clase Control, aunque la palabra Control no
aparece en su nombre.

✓ Utilizar el prefijo “I” en los nombres de las interfaces para indicar que el tipo es una interface.

Por ejemplo, IComponent (sustantivo descriptivo), ICustomAttributeProvider (frase adjetiva),


o IPersistable (adjetivo) son nombres adecuados para una interface. Al igual que con otros
nombres de tipo, debemos evitar las abreviaturas.

Algunos miembros del equipo de desarrollo de Microsoft proponen el uso del prefijo “I” para
los nombres de interfaces mientras otros miembros no lo consideran necesario.

El uso del prefijo “I” es una clara prueba de la influencia de los componentes COM y de Java
sobre el .NET Framework. COM popularizó e institucionalizó el uso del prefijo “I” en las
interfaces y se siguió esta nomenclatura en el .NET Framework pensando en los
desarrolladores familiarizados con COM.

Algunos miembros del equipo de desarrollo Microsoft argumentan que el uso del prefijo “I”
es otra aplicación de la notación Húngara con las mismas desventajas que representa su uso
en el nombre de variables.

Como nota curiosa, la interface _AppDomain del .NET Framework es una interface definida
en el espacio de nombres System que no sigue esta recomendación.

✓ Asegurarse de que los nombres difieren solo con el prefijo “I” en el nombre de la interface
cuando se define un par clase-interface donde la clase es una implementación estándar de la
interface.

El siguiente ejemplo ilustra esta recomendación para la interface IRepository y su


implementación Repository.

public interface IRepository { }


public class Repository : IRepository { }

Un dato curioso de violación a esta recomendación en el .NET Framework es la clase


HttpSessionState que no implementa (como podría esperarse) la interface IHttpSessionState.

32 https://ticapacitacion.com/curso/arquitecturanet
Este manual fue creado por TI Capacitación para uso personal de:
Ivan Elias Carrasco Lupinta (rimanace@hotmail.com)
Guías para diseño de aplicaciones y componentes .NET
Implementando una convención de nombres apropiada

Nombres de parámetros de tipos genéricos


Los tipos Genéricos fueron agregados en el .NET Framework 2.0. La característica introdujo un nuevo
tipo de identificador llamado parámetro de tipo (type parameter).

Las siguientes recomendaciones describen las convenciones de nombres relacionadas con los
parámetros de tipo:

✓ Nombrar los parámetros de tipo genérico con nombres descriptivos a menos que un nombre
con una sola letra sea suficientemente explicativo y un nombre descriptivo no agregue ningún
valor.

public interface ISessionChanel<TSession> { . . . }


public delegate TOutput Converter<TInput, TOutput>(TInput from);
public class Nullable<T> { . . . }
public class List<T> { . . . }

✓ Considerar el uso de T como el nombre del parámetro de tipo para tipos con nombres de una
sola letra.

public int IComparer<T> { . . . }


public delegate bool Predicate<T>(T item);
public struct Nullable<T> where T : struct { . . . }

✓ Agregar al nombre del parámetro de tipo el prefijo T en el caso de nombres descriptivos.

public interface ISessionChannel<TSession> where TSession : ISession


{
TSession Session { get; }
}

✓ Considerar la colocación de la restricción en el nombre de parámetro de tipo en el caso de


que el parámetro de tipo incluya una.

Por ejemplo, un parámetro restringido a Session puede ser llamado TSession.

public interface ISessionChannel<TSession> where TSession : Session


{
TSession Session { get; }
}

33 https://ticapacitacion.com/curso/arquitecturanet
Este manual fue creado por TI Capacitación para uso personal de:
Ivan Elias Carrasco Lupinta (rimanace@hotmail.com)
Guías para diseño de aplicaciones y componentes .NET
Implementando una convención de nombres apropiada

Nombres de tipos comunes


Si estamos derivando o implementando tipos contenidos en .NET, es importante seguir las
recomendaciones que se muestran en la siguiente tabla:

Tipo base Regla para el tipo derivado o la implementación

System.Attribute ✓ Agregar el sufijo "Attribute" a los nombres de clases de atributos


personalizados.
System.Delegate
✓ Agregar el sufijo "EventHandler" a los nombres de los delegados
que se usan en los eventos.

✓ Agregar el sufijo "Callback" a los nombres de los delegados


distintos a los utilizados como manejadores de eventos.

 No utilizar el sufijo "Delegate" para un delegado.

System.EventArgs ✓ Agregar el sufijo "EventArgs".


System.Enum
 No derivar tipos de esta clase, en lugar de eso, utilizar la palabra
clave soportada por el lenguaje, por ejemplo, en C#, utilizar la
palabra clave enum.
 No agregar el sufijo "Enum" o "Flag".

System.Exception ✓ Agregar el sufijo “Exception”

IDictionary ✓ Agregar el sufijo "Dictionary". Debemos tomar en cuenta que


IDictionary<TKey,TValue> IDictionary es un tipo específico de colección y que esta regla
tiene prioridad sobre la regla más general para colecciones
siguiente.

IEnumerable, ICollection ✓ Agregar el sufijo "Collection".


IList, IEnumerable<T>,
ICollection<T>, IList<T>

System.IO.Stream ✓ Agregar el sufijo "Stream".


CodeAccessPermission ✓ Agregar el sufijo "Permission".
IPermission

34 https://ticapacitacion.com/curso/arquitecturanet
Este manual fue creado por TI Capacitación para uso personal de:
Ivan Elias Carrasco Lupinta (rimanace@hotmail.com)
Guías para diseño de aplicaciones y componentes .NET
Implementando una convención de nombres apropiada

Nomenclatura para enumeraciones


En general, los nombres de tipos enumeración (también denominados enumeraciones) deben seguir
las reglas de nomenclatura de tipos estándar (PascalCasing, etc.). Sin embargo, hay directrices
adicionales que se aplican específicamente a las enumeraciones.

Recomendaciones:

✓ Utilizar un nombre de tipo en singular para una enumeración a menos que los valores sean
campos de tipo bit.

public enum ProductColor


{
Black,
Red,
Green
}

✓ Utilizar un nombre en plural para una enumeración con campos de tipo bit como valores,
también llamadas enumeraciones Flag.

[Flags]
public enum ProductColors
{
Red,
Green,
Blue
}

 No utilizar el sufijo “Enum” en nombres de tipos enumeración.

// Incorrecto
public enum ProductColorEnum
{
Black,
Red,
Green
}

 No utilizar el sufijo “Flag” o “Flags” en los nombres de tipos enumeración.

// Incorrecto
[Flags]
public enum ProductColorFlags
{
Red,
Green,
Blue
}

35 https://ticapacitacion.com/curso/arquitecturanet
Este manual fue creado por TI Capacitación para uso personal de:
Ivan Elias Carrasco Lupinta (rimanace@hotmail.com)
Guías para diseño de aplicaciones y componentes .NET
Implementando una convención de nombres apropiada

 No utilizar un prefijo en los nombres de los valores de una enumeración. Por ejemplo: “ad”
para enumeraciones de ADO, “rtf” para enumeraciones de texto enriquecido (Rich Text), etc.

// No recomendado. El prefijo ImageMode no es necesario.


public enum ImageMode
{
ImageModeBitMap,
ImageModeGrayScale,
ImageModeIndexed,
ImageModeRgb
}

// Recomendado
public enum ImageMode
{
BitMap,
GrayScale,
ModeIndexed,
Rgb
}

36 https://ticapacitacion.com/curso/arquitecturanet
Este manual fue creado por TI Capacitación para uso personal de:
Ivan Elias Carrasco Lupinta (rimanace@hotmail.com)
Guías para diseño de aplicaciones y componentes .NET
Implementando una convención de nombres apropiada

Lección 5
Nombres de miembros de tipos
Los tipos están conformados por miembros: métodos, propiedades, eventos, constructores y campos.
En esta lección se describen las guías para nombrar los miembros de tipos.

Objetivos de la lección
Al finalizar esta lección, los participantes podrán:

• Elegir nombres apropiados para los métodos, propiedades, eventos y campos de un tipo.

37 https://ticapacitacion.com/curso/arquitecturanet
Este manual fue creado por TI Capacitación para uso personal de:
Ivan Elias Carrasco Lupinta (rimanace@hotmail.com)
Guías para diseño de aplicaciones y componentes .NET
Implementando una convención de nombres apropiada

Nombres de métodos
Dado que los métodos son los medios para realizar una acción, las guías de diseño requieren que los
nombres de los métodos sean verbos o frases verbales. Seguir esta guía también sirve para distinguir
nombres de métodos de los nombres de propiedades y de los nombres de tipos que son sustantivos o
frases nominales.

Recomendación:

✓ Proporcionar nombres de métodos que sean verbos o frases verbales y que identifiquen
fácilmente la tarea que realizan y no algún detalle de implementación.

Por ejemplo, la clase String expone los siguientes métodos:

public class String


{
public int CompareTo(...);
public string[] Split(...);
public string Trim();
}

38 https://ticapacitacion.com/curso/arquitecturanet
Este manual fue creado por TI Capacitación para uso personal de:
Ivan Elias Carrasco Lupinta (rimanace@hotmail.com)
Guías para diseño de aplicaciones y componentes .NET
Implementando una convención de nombres apropiada

Nombres de propiedades
A diferencia de otros miembros, las propiedades deben tener nombres de sustantivos o adjetivos. Esto
es debido a que una propiedad hace referencia a datos y el nombre de la propiedad refleja eso. Los
nombres de propiedades siempre se escriben con el formato PascalCasing.

Recomendaciones:

✓ Nombrar las propiedades utilizando sustantivos, frases nominales o adjetivos.

public int Length { get; set; }


public string TextWriter { get; set; }
public bool Enabled { get; set; }
 No utilizar nombres de propiedades que coincidan con los nombres de métodos Get como en
el siguiente ejemplo:

public string TextWriter { get; set; }


public string GetTextWriter(int value) { return ""; }

Típicamente, este patrón suele indicar que la propiedad en realidad debería ser un método.

✓ Nombrar las propiedades de tipo colección con una frase en plural describiendo los elementos
en la colección en lugar de utilizar una frase en singular seguida de las palabras "List" o
"Collection".

// Correcto
public Stack Items { get; set; }

// Incorrecto
public Stack ItemCollection { get; set; }

✓ Elegir frases afirmativas para los nombres de propiedades booleanas. Por ejemplo, CanSeek
es preferible a CantSeek. Opcionalmente podemos agregar el prefijo “Is”, “Can” o “Has” a las
propiedades de tipo booleano solo cuando realmente le agreguen un valor.

Por ejemplo, CanRead es más entendible que Readable. Sin embargo, Created es más
entendible que IsCreated.

✓ Considerar asignar a la propiedad el mismo nombre que su tipo.

Por ejemplo, la siguiente propiedad permite obtener y establecer correctamente un valor de


enumeración llamado Color, por lo tanto, el nombre de la propiedad puede ser Color.

public enum Color {...}

public Color Color { get {...} set {...} }

39 https://ticapacitacion.com/curso/arquitecturanet
Este manual fue creado por TI Capacitación para uso personal de:
Ivan Elias Carrasco Lupinta (rimanace@hotmail.com)
Guías para diseño de aplicaciones y componentes .NET
Implementando una convención de nombres apropiada

Nombres de eventos
Los eventos siempre hacen referencia a alguna acción, ya sea una acción que está ocurriendo o una
acción que ya ha ocurrido. Por lo tanto, al igual que con los métodos, los eventos son nombrados con
verbos. El tiempo verbal es utilizado para indicar el momento en que el evento es lanzado.

Recomendaciones:

✓ Nombrar los eventos con un verbo o frases verbales.

Por ejemplo, Clicked, Painting, DroppedDown, etc.

✓ Proporcionar al nombre del evento el concepto del antes y el después mediante la utilización
de los tiempos presente y pasado.

Por ejemplo, un evento Close que sea lanzado antes de que un objeto Window sea cerrado
podría ser llamado Closing mientras que el evento que sea lanzado después de que el objeto
Window haya sido cerrado podría llamarse Closed.

 No utilizar los prefijos o sufijos "Before" o "After" para indicar los eventos antes y después. En
lugar de eso, se deben utilizar los tiempos verbales presente y pasado.

✓ Nombrar a los manejadores de eventos (delegados utilizados como tipos de eventos) con el
sufijo " EventHandler", como se muestra en el ejemplo siguiente:

public delegate void ClickedEventHandler(object sender, ClickedEventArgs e);

✓ Utilizar dos parámetros llamados “sender” y “e” en los manejadores de eventos.

El parámetro sender representa al objeto que dispara el evento. El parámetro sender es


típicamente de tipo object, incluso aunque sea posible utilizar un tipo que sea más específico.

public delegate void <EventName>EventHandler(object sender, <EventName>EventArgs e);

✓ Nombrar a las clases utilizadas como argumento de eventos utilizando el sufijo “EventArgs”.

public class ClickedEventArgs : EventArgs


{

. . .
}

40 https://ticapacitacion.com/curso/arquitecturanet
Este manual fue creado por TI Capacitación para uso personal de:
Ivan Elias Carrasco Lupinta (rimanace@hotmail.com)
Guías para diseño de aplicaciones y componentes .NET
Implementando una convención de nombres apropiada

Nombres de Campos
Las guías para los nombres de campos aplican a campos estáticos public o protected. Los campos
private e internal no son cubiertos por las guías. Los campos de instancia public o protected no son
permitidos por las guías de diseño de miembros de tipos.

Recomendaciones:

✓ Utilizar PascalCasing en los nombres de campos.

public static string UserName;

✓ Nombrar los campos utilizando un sustantivo, una frase nominal o un adjetivo.

public static string UserName;


public static string AlternateUserName;
public static bool Enabled;

 No utilizar un prefijo para los nombres de los campos.

Por ejemplo, no utilizar “g_” o “s_” pata indicar campos estáticos. Los campos accesibles
públicamente (el objetivo de este tema) son muy similares a las propiedades desde el punto
de vista de diseño de APIs, por lo tanto, deben seguir la misma convención de nombres de las
propiedades.

41 https://ticapacitacion.com/curso/arquitecturanet
Este manual fue creado por TI Capacitación para uso personal de:
Ivan Elias Carrasco Lupinta (rimanace@hotmail.com)
Guías para diseño de aplicaciones y componentes .NET
Implementando una convención de nombres apropiada

Lección 6
Nombres de Parámetros y Recursos
En esta lección se describe la nomenclatura para establecer nombres apropiados a parámetros de
métodos, así como la nomenclatura para establecer nombres a los identificadores de los recursos
utilizados dentro de la aplicación.

Objetivos de la lección
Al finalizar esta lección, los participantes podrán:

• Nombrar adecuadamente los parámetros de métodos.


• Nombrar adecuadamente los identificadores de recursos.

42 https://ticapacitacion.com/curso/arquitecturanet
Este manual fue creado por TI Capacitación para uso personal de:
Ivan Elias Carrasco Lupinta (rimanace@hotmail.com)
Guías para diseño de aplicaciones y componentes .NET
Implementando una convención de nombres apropiada

Nombrando parámetros
Más allá de la obvia razón de legibilidad, es importante seguir las guías para los nombres de parámetros
debido a que los parámetros son mostrados en la documentación y en el diseñador cuando las
herramientas de diseño visual proporcionan Intellisense y la funcionalidad de exploración de clases.

Recomendaciones:

✓ Utilizar camelCasing en los nombres de parámetros.

public bool Contains(string value) { . . . }


public string Remove(int startIndex, int count) { . . . }

✓ Utilizar nombres de parámetros descriptivos.

El nombre de un parámetro debe ser lo suficientemente descriptivo de tal forma que, junto
con su tipo, en la mayoría de los escenarios, se pueda identificar su propósito.

✓ Considerar el uso de nombres basados en el propósito del parámetro en lugar del tipo del
parámetro.

Nombrando parametros de sobrecarga de operadores

✓ Utilizar left y right para nombres de parámetros de sobrecarga de operadores binarios si no


hay ningún nombre significativo para los parámetros.

public class Complex


{
public int Real { get; set; }
public int Imaginary { get; set; }
public Complex(int real, int imaginary)
{
this.Real = real;
this.Imaginary = imaginary;
}
public static Complex operator -(Complex left, Complex right)
{
return new Complex(left.Real - right.Real,
left.Imaginary - right.Imaginary);
}
}

✓ Utilizar value como nombre para un parámetro de sobrecarga de operador unario en caso de
que no haya algún nombre significativo para el parámetro.

public static Complex operator -(Complex value)


{
return new Complex(-value.Real, -value.Imaginary);
}

43 https://ticapacitacion.com/curso/arquitecturanet
Este manual fue creado por TI Capacitación para uso personal de:
Ivan Elias Carrasco Lupinta (rimanace@hotmail.com)
Guías para diseño de aplicaciones y componentes .NET
Implementando una convención de nombres apropiada

✓ Considerar el uso de nombres significativos para parámetros de sobrecarga de operadores si


al hacerlo agrega un valor significativo.

public static Complex operator /(Complex dividend, Complex divisor)


{

. . .
}

 No utilizar abreviaciones o índices numéricos para los nombres de parámetros de sobrecarga


de operadores.

// Incorrecto
public static Complex operator /(Complex c1, Complex c2)
{

. . .
}

44 https://ticapacitacion.com/curso/arquitecturanet
Este manual fue creado por TI Capacitación para uso personal de:
Ivan Elias Carrasco Lupinta (rimanace@hotmail.com)
Guías para diseño de aplicaciones y componentes .NET
Implementando una convención de nombres apropiada

Nombrando recursos
Debido a que los recursos pueden ser referenciados a través de objetos como si fueran propiedades,
las guías de nomenclatura para los recursos son similares a las guías aplicadas a las propiedades.

Recomendaciones:

✓ Utilizar PascalCasing en los nombres de los recursos.

✓ Proporcionar un nombre descriptivo en lugar de un nombre corto. No debemos sacrificar


legibilidad por espacio.

 No utilizar palabras reservadas específicas de los principales lenguajes CLR.

✓ Utilizar solo caracteres alfanuméricos y guion bajo en los nombres de recursos.

✓ Utilizar la siguiente convención de nomenclatura para los recursos de mensajes de excepción.

El identificador de recurso debe ser el nombre del tipo de excepción más un identificador corto
de la excepción. Por ejemplo:

ArgumentExceptionIllegalCharacters
ArgumentExceptionInvalidName
ArgumentExceptionFileNameIsMalformed

45 https://ticapacitacion.com/curso/arquitecturanet
Este manual fue creado por TI Capacitación para uso personal de:
Ivan Elias Carrasco Lupinta (rimanace@hotmail.com)
Guías para diseño de aplicaciones y componentes .NET
Implementando una convención de nombres apropiada

En resumen, las guías de nombres proporcionadas en este documento, si son seguidas, proporcionan
un esquema consistente que facilitará a los usuarios de un framework identificar la función de los
elementos de ese framework. Las guías proporcionan una consistencia de nombres a través de los
frameworks desarrollados por diferentes organizaciones o empresas.

46 https://ticapacitacion.com/curso/arquitecturanet
Este manual fue creado por TI Capacitación para uso personal de:
Ivan Elias Carrasco Lupinta (rimanace@hotmail.com)