Ir al contenido



Foto

Definiendo un sistema de versión para nuestras nomenclaturas


  • Por favor identifícate para responder
7 respuestas en este tema

#1 Delphius

Delphius

    Advanced Member

  • Administrador
  • 6.000 mensajes
  • LocationArgentina

Escrito 29 diciembre 2016 - 07:49

Quizá lo que pregunte esté medio loco... pero me pregunto ¿Impondrías un sistema de versión o algun criterio de identificación a un documento en el que se define los criterios de nomenclatura a usar en tu código y en el de tu equipo? ¿O esto es ya ir demasiado lejos y liarse demasiado?

 

Veran... yo tengo definido ya una forma (un sistema o método, como prefieran llamarlo) de como nombrar mis clases, variables, tipos, etc. pero en ocasiones me he visto condicionado a ir mejorándolo o cambiando algunas de sus reglas para adaptarse a nuevas cosas... como por ejemplos esto de los Helpers, Numerators, Genéricos, que fueron incorporándose al lenguaje.

 

Mi método tiene como una de sus reglas bases que se debe respetar el estándar Object Pascal que tanto Delphi como Lazarus se esfuerzan en seguir, la segunda regla base es que prima los nombres que derivan del contexto y/o las referencias de consultas (como ser libros, artículos, palabras técnicas propias del ambiente, siglas estándars, etc)

Pero adicionalmente cada quien adereza las cosas según su experiencia, necesidades, etc. Y esto es fundamental hacerlo bien para que en el día de mañana cuando uno lea el nombre de algo le sea aclaratorio y no que le suene confuso. Porque luego puede pasar que ve un identificador llamado de cierta forma y al mes siguiente se encuentra que le "hace ruido".

 

Cambiarlo sobre la marcha, y sin un criterio establecido medianamente formal hace que llegue el momento en el que todo termina "sonando mal" y el estilo que hemos planteado inicialmente ha sido destrozado. Se pone peor cuando en un proyecto decidimos hacerlo como X, y luego en otro cambiamos por simple gusto a uno Z.

 

A mi me ha pasado,  y es por ello que me he llegado a preguntar si no estaría mal llevar alguna especie de versión, como para lograr establecer algún control.

Algo como para decir: "A partir de la fecha xx/yy/zz a los identificadores de variables se debe aplicar la regla pp de desempate de nombre" o poder incluso asociar los cambios que uno efectúa en el código: "Se ha cambiado el nombre de la clase TPersons por TPersonList según la sugerencia dada por la regla mm que establece que los objetos que forman una lista o agrupación tengan el sufijo List" y dar peso a nuestras decisiones que afecten el diseño.

 

El otro motivo por el que he llegado a pensar que tuviera sentido ponerle algún sistema de versión es poder llegar a saber en que momento es que se ha pasado de un criterio a otro. Llevarlo de forma consciente. Sobre todo cuando en el medio hemos estado haciendo cambio de versiones a nuestras units, etc:

 

12/12/2016 Unidad: UStocks v: 1.2.3.4 - Nomeclatura v: 1.1

15/12/2016 Se añadieron nuevas reglas al documento de Nomeclatura. Cambió a la versión v 1.2

16/12/2016 Unidad UStocks v: 1.2.3.5 - Nomeclatura v: 1.2 Motivo: El documento v.1.2 promueve cambios que afectaron la unidad. Se aconseja subir el número de version menor por adaptarse a la nueva nomeclatura.

23/12/2016 Unidad UStocks v: 1.3.1.0 - Nomeclatura v: 1.2

....

 

Si no es decabellado pensar en esto, mi pregunta es, ¿que sistema escalable de versión podría emplear?

Mi nomeclatura se basa en reglas. No son muchas, ni rebuscadas (hasta el momento a mi todavía me suenan a sentido común), pero las hay tanto generales y comunes a todos los elementos, como específicas (por ejemplo, reglas que hacen a las variables, otras que hacen a las clases, otra para los componentes visuales, etc)

Un cambio en una regla específica implicará grandes cambios ya que afecta en un todo, mientras que una nueva regla para algún elemento no trae ni justifica un cambio de arrastre o efecto en cascada. Debiera ser algo menor.

Ando pensando en como hacerlo lo más simple posible, porque tampoco quisiera llegar al punto de tener que rizar más el rizo y tener un sistema de versión paralelo que termine siendo un tremeno sotobosque.

 

Tampoco es que todos los días cambio las reglas, pero cuando noto que alguna queda desfazada o que aparecen ambigüedades (un posible ejemplo reciente lo podríamos ver en este hilo de Agustín) siento que es hora de ajustar las cosas.

 

Estoy justo en un proceso de reingeniería que venía postergando... porque no estuve documentando  8o|  (Niños eso no se hace... siempre documenten :D ) y bueno... me ha tocado volver a poner orden a la casa. :D

 

Estoy pensando en llevar mis reglas de forma que pueda identificarlas:

R-<Nro>-<Fecha>: regla general

R.<Nomeclador>-<Nro>-<Fecha>: regla específica para el nomeclador. Por ejemplo: R-VAR-1-03062015 hace la regla #1 de las variables dictada el día 03/06/2015 (formato: dd/mm/yyyy)

Y si tengo que hacer un cambio a una regla simplemente se hace una "sub-rama" identificada por la fecha, así que siguiendo el ejemplo anterior podría decir R-VAR-1-24112016 y por tanto la regla vigente es la fecha más reciente o la última derivación.

 

Hasta el momento las tenía todas siguiendo el orden... del #1 al #3 las específicas, de las #4 a la #7 para las variables, etc. Y pienso que con esta reforma se puede ser más fácil agregar cosas sin romper la numeración, y además hasta siento que podría definir las reglas (y otras nuevas) casi "al vuelo" en la medida en que uno avanza en su estilo de programación y aprende nuevas cosas.

 

¿Ustedes tienen algún criterio sobre esto?

 

Saludos,


  • 0

#2 escafandra

escafandra

    Advanced Member

  • Moderadores
  • PipPipPip
  • 3.696 mensajes
  • LocationMadrid - España

Escrito 29 diciembre 2016 - 09:43

Yo uso nombres descriptivos y casi siempre en inglés por ser más sintético. Uso reglas en librerías de clases para tratar de dar lógica intuitiva a las clases derivadas y relacionadas con otras. Los tipos que defino como punteros los inicio con P y suelo escribirlos en mayúsculas. En el resto de variables intercalo mayúsculas y minúsculas cuando usan más de una palabra en su descripción. Docuento  escuetamente el código y suelo hacerlo por pasos de solución de problemas parciales o cuando se me ha ocurrido una solución muy sintética. Suelo documentar al principio de una función o clase que hace y su sintáxis de uso. No escribo reglas de nomenclatura. Entiendo bien mi código antiguo.

 

Saludos.


  • 0

#3 Delphius

Delphius

    Advanced Member

  • Administrador
  • 6.000 mensajes
  • LocationArgentina

Escrito 29 diciembre 2016 - 10:20

Yo uso nombres descriptivos y casi siempre en inglés por ser más sintético. Uso reglas en librerías de clases para tratar de dar lógica intuitiva a las clases derivadas y relacionadas con otras. Los tipos que defino como punteros los inicio con P y suelo escribirlos en mayúsculas. En el resto de variables intercalo mayúsculas y minúsculas cuando usan más de una palabra en su descripción. Docuento  escuetamente el código y suelo hacerlo por pasos de solución de problemas parciales o cuando se me ha ocurrido una solución muy sintética. Suelo documentar al principio de una función o clase que hace y su sintáxis de uso. No escribo reglas de nomenclatura. Entiendo bien mi código antiguo.

 

Saludos.

 

Yo como base tengo establecido:

1. Se programa en inglés.

2. Se documenta en español.

3. Se respeta las reglas de estilo del lenguaje. Para el caso de Object Pascal implica unas cuantas cosas como ser: los atributos de clases tienen el sufijo f, los punteros se nombran con P, los tipos, sobre todo las clases, tienen el sufijo T, los enumerados siguen como sufijo las letras capitales del nombre, los nombres están expresados en CamelCase (aunque muchos sostienen que en Object Pascal en realidad se habla del estilo PascalCase), etc.

4. Los nombres de todo elemento deben estar basados por el dominio o contexto.

 

Luego tengo unas reglas para el nombrado de variables, contantes, y la forma de como nombrar los componentes (en éste es donde tengo más reglas y pueden ser confusas por su complejidad) y otras cosas.

 

Mi estilo de documentar unit se basa en tener una sección al comienzo de cada unit a modo de "presentación" y luego antes de cada elemento (clase, tipo, etc) dispongo de mis plantillas diseñadas para cada uno. Documento en la sección interface y algunos cuantos comentarios en implementation y algunos TODOs para hacerme una mejor idea de lo que hago.

 

 

Suelo documentar cuando llego a un buen grado de madurez en mis units, o bien cuando veo que llegué a una cantidad considerable de código o he estado realizando muchos cambios. Pero ultimamente he priorizado más picar código y documentar menos... y estoy notando que algunas cosas no me están cuadrando y estuve olvidando/obviando algunas reglas y se está volviendo confuso.

Veo el "estilo" en un proyecto y lo comparo con otro proyecto, y me "desentona" :(   Algunas reglas las voy a tener que hacer desaparecer o ser un poco más laxo, y en otras ser más estricto.

 

Saludos,


  • 0

#4 Agustin Ortu

Agustin Ortu

    Advanced Member

  • Moderadores
  • PipPipPip
  • 802 mensajes
  • LocationArgentina

Escrito 30 diciembre 2016 - 12:08

A mi me parece demasiado. Pero es un tema personal. Me gusta experimentar y probar cosas nuevas todo el tiempo y no quedarme con una sola forma de hacer las cosas

Se que muchos opinan que lo más adecuado sea establecer reglas, criterios, normas, estilos, convenciones, documentarlo todo bien prolijo y luego respetarlo. Quizá sea lo mejor

Pero como decía, yo no encajo. Yo agarro codigo que escribí ayer y no se porque me aborda un deseo incontenible de toquetearlo todo, renombrando variables, métodos, parámetros, clases, creando nuevas unit... De llevar un documento aparte de como serían las normas me llevaría más tiempo que el código que está detrás!!
  • 0

#5 Delphius

Delphius

    Advanced Member

  • Administrador
  • 6.000 mensajes
  • LocationArgentina

Escrito 30 diciembre 2016 - 06:29

A mi me parece demasiado. Pero es un tema personal. Me gusta experimentar y probar cosas nuevas todo el tiempo y no quedarme con una sola forma de hacer las cosas

Se que muchos opinan que lo más adecuado sea establecer reglas, criterios, normas, estilos, convenciones, documentarlo todo bien prolijo y luego respetarlo. Quizá sea lo mejor

Pero como decía, yo no encajo. Yo agarro codigo que escribí ayer y no se porque me aborda un deseo incontenible de toquetearlo todo, renombrando variables, métodos, parámetros, clases, creando nuevas unit... De llevar un documento aparte de como serían las normas me llevaría más tiempo que el código que está detrás!!

 

Yo soy de los que si está andando, mejor no tocarlo.

Pero cuando veo que la cosa se amplió mucho, o me fui demasiado por la tangente en algún diseño que podría ser más simple (alías esos momentos "y si cambiara alguito...") llega la hora de revisar y ahí es cuando se me aparece NewDelphius y empieza a revolear las cosas cambiando clases, partiendo una unit en 2 o más, etc.

Y al multiplicarlo por varios módulos, ya no es cosa de que sea un juego.

 

Eso de que hoy me levanto y decido nombrar a una clase como TCustomAccountEntry y mañana le cambio por el TAbstractAccountSeat, por dar un ejemplo quizá no pueda ser evitable; cambios seguro que los hay y van a seguir apareciendo. Lo que me gustaría es poder darle un poco más de criterio, como para decir también "Momento, ¿estás seguro de lo que vas a hacer?". Sobre todo cuando se trata de tocar unidades básicas de las que mis proyectos dependen.

 

Saludos,


  • 1

#6 escafandra

escafandra

    Advanced Member

  • Moderadores
  • PipPipPip
  • 3.696 mensajes
  • LocationMadrid - España

Escrito 30 diciembre 2016 - 10:06

Yo no me conformo con que algo funcione. lo toco y retoco en el momento y a veces, meses después.  Suelo guardar varias versiones de hacer lo mismo con cambios fundamentales en el código, para tener una referencia de lo que cambié en su momento y porqué.

 

Saludos.


  • 1

#7 Delphius

Delphius

    Advanced Member

  • Administrador
  • 6.000 mensajes
  • LocationArgentina

Escrito 30 diciembre 2016 - 10:53

Los procesos de reingeniería son inevitables. Vamos a estar toqueteando nuetros trabajos muy seguido.

Y para eso hay que ser ordenados, y la disciplina de Ingeniería de Software ofrece unas cuantas buenas prácticas que nos pueden facilitar la vida.

 

Pero en cuanto al "estilo" no se mete, ba... yo al menos no he estudiado ni visto en cátedra algo que vaya en ese sentido. Y como dice Agustín es una apreciación ya más de índole personal.

Puede que en el plan de documentación que uno se establece sea suficiente con tener algo tan simple como un:


delphi
  1. {
  2. ...
  3. Historial:
  4. v1.2.3.4
  5. [=] Cambiados los prefijos de constantes INFO_ por DATA_
  6. [+] Añadido el tipo enumerativo TMetaData
  7. [-] Eliminada la clase TDataType
  8. [*] En planificación: hacer de la clase TDataBase un wrapper de la biblioteca TXSysData
  9. v1.2.2.0
  10. ...
  11. }

Por poner un ejemplo inventado al momento.

Eso ya uno de una u otra forma lo hace, más o menos elaborado y de forma manual, o semi automática...

 

La cosa pasa por abordar un estilo de nomeclatura estándar, que permita ser tanto ampliable como así también que no sea demasiado riguroso pero tampoco que sea muy permisivo.

Hoy estoy más abierto a la posibilidad de usar prefijos... No tanto como algunas suites, que le ponen sus prefijos a todo. Pero si, a algunas cosas, como a las units como para distinguir a las propias de las que cuenta el lenguaje y de las de terceros.

Ya vengo usando algo de prefijos; asi que ¿porqué no? Si tengo ya bastante aplicado un sistema inspirado en la notación hungara para el nombrado de los componentes y controles. Esto me permite reconocer el tipo de componente de manera sencilla. Aunque claro, la notación húngara no es muy aconsejable en la guía de estilo de Object Pascal y hoy hay más detractores que defensores de ésta corriente.

 

Saludos,


  • 0

#8 Nikolas

Nikolas

    Advanced Member

  • Miembro Platino
  • PipPipPip
  • 591 mensajes
  • LocationMar del Plata / Bs As / Argentina

Escrito 01 enero 2017 - 08:44

un tema muy complicado de debatir, en mi caso siempre estoy buscando nuevas nomenclaturas para mejor en la calidad. por ejemplo

cliente_detalle,proveedor_detalle,articulo_detalle, son los casos que se me vienen ahora a la mente.


  • 0