Documenti di Didattica
Documenti di Professioni
Documenti di Cultura
NET
Implementando una convención de nombres apropiada
Este manual fue creado por TI Capacitación para uso personal de:
1 https://ticapacitacion.com/curso/arquitecturanet
Guías para diseño de aplicaciones y componentes .NET
Implementando una convención de nombres apropiada
Contenido
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
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
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:
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
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:
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
• 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
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.
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.
Recomendaciones:
System.IO
public void StartIO(Stream ioStream)
System.Xml
public void ProcessXmlTag(string xmlTag)
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
• Forma abierta. Escritas como 2 o más palabras separadas por espacio. Ejemplos:
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
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
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:
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.
Evitar el uso de identificadores que hagan conflicto con palabras clave utilizadas ampliamente
en los lenguajes de programación.
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
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
Recomendaciones:
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
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++.
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
✓ 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.
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
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.
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
✓ 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
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:
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
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.
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.
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
<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
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.
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
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
Recomendaciones:
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:
Recomendació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
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.
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.
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.
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
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:
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.
✓ 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.
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.
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
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.
✓ Considerar el uso de T como el nombre del parámetro de tipo para tipos con nombres de una
sola letra.
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
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
Recomendaciones:
✓ Utilizar un nombre de tipo en singular para una enumeración a menos que los valores sean
campos de tipo bit.
✓ 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
}
// Incorrecto
public enum ProductColorEnum
{
Black,
Red,
Green
}
// 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.
// 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.
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:
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.
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:
✓ 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:
✓ Nombrar a las clases utilizadas como argumento de eventos utilizando el sufijo “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:
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:
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:
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.
✓ 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.
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
. . .
}
// 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:
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)