En esta nota vamos a ver cómo crear un Snippet en Visual Studio para favorecer la búsqueda de modificaciones en las distintas versiones de una aplicación, a través de los cambios que vayamos realizando en el código fuente.
A mi particularmente me ayuda a mantener la paz y el orden el dejar bien claras las modificaciones que hago en cada release de una aplicación, indicando los cambios con comentarios en el código. Si bien hay distintas formas de numerar las versiones, a mi me gusta utilizar la convención de versionado basada en cuatro posiciones numéricas, como 1.0.0.0.
En proyectos grandes, a veces se hace difícil identificar qué cambios se hicieron, cuándo y en qué versión, y es por eso que llevo el código con comentarios ordenados, especialmente cuando soy de los que no recuerdan qué hice el día anterior ;)
Es así que para ordenar los comentarios e identificar los cambios en el código me valgo de comentarios de este tipo:
/* MODIF v 1.0.2.7 - REVISIÓN- 15/02/2013 (Marcelo)
* Este es un comentario de prueba.
* viernes, 15 de febrero de 2013 por Marcelo a las 07:52:41
*/
* Este es un comentario de prueba.
* viernes, 15 de febrero de 2013 por Marcelo a las 07:52:41
*/
En Visual Studio se pueden configurar identificadores para las tareas, por lo que la idea aquí es que en la ventana de tareas (Task List) se encuentren listados todos los comentarios "MODIF", y que al darle doble clic nos lleve directo al código en cuestión.
 |
| Ventana Task List con lista de comentarios. |
En el siguiente video se ve cómo funciona y como poner el ejemplo en práctica. Más abajo veremos cómo hacer cada cosa paso a paso.
¿Y con qué?
Para automatizar los comentarios de las versiones vamos a crear un snippet y una macro para Visual Studio. Los snippet son fragmentos de código que se escriben rápidamente mediante un atajo del IntelliSense de Visual Studio, mientras que las macros son programas escritos en VBA que permiten automatizar tareas.
El snippet va a introducir el comentario, y la macro va a establecer la fecha y hora de la modificación, admás del autor (el usuario de Windows). Tendremos que escribir el número de versión sobre la que estamos trabajando, una referencia (la que se verá en el listado de la lista de tareas) y el comentario de la modificación que estamos haciendo, lo más detallado y claro posible (como para que lo entiendan otros, además de nosotros ¿no?).
El ejemplo que vamos a ver es para C# y Visual Studio 2010. Imagino que para otras versiones podría ser necesario hacer algunos cambios.
Manos a la obra.
El primer paso es construir el snippet. Si bien en CodePlex hay una excelente herramienta para diseñar snippets (Snippet Designer) para Visual Studio, yo lo voy a hacer "a mano".
Paso 1: Crear e instalar el Snippet
El snippet es un archivo XML que responde a un schema determinado y tiene extensión .snippet. El archivo se guarda normalmente en la carpeta de Snippets de Visual Studio, que dependiendo de la versión, generalmente podría estar en alguna de estas rutas:
- C:\Program Files (x86)\Microsoft Visual Studio 10.0\VC#\Snippets\1033\Visual C#
- C:\Program Files\Microsoft Visual Studio 10.0\VC#\Snippets\1033\Visual C#
No voy a expicar la estructura del XML del snippet (se puede encontrar información en este link).
He aquí el código para este ejemplo (se puede editar con cualquier archivo de texto).
Luego guardar el archivo con el nombre MODIF.snippet en la carpeta de snippet de Visual Studio correspondiente (alguna de las mostradas arriba).
</Description>
<HelpUrl>
</HelpUrl>
<Shortcut>MODIF</Shortcut>
</Header>
<Snippet>
<Declarations>
<Object Editable="true">
<ID>MAJOR</ID>
<ToolTip>Version MAJOR (verifique la versión de la aplicación en desarrollo)</ToolTip>
<Default>0</Default>
<Function>
</Function>
<Type>System.Int32</Type>
</Object>
<Object Editable="true">
<ID>MINOR</ID>
<ToolTip>Version MINOR (verifique la versión de la aplicación en desarrollo)</ToolTip>
<Default>1</Default>
<Function>
</Function>
<Type>System.Int32</Type>
</Object>
<Object Editable="true">
<ID>BUILD</ID>
<ToolTip>Version BUILD (verifique la versión de la aplicación en desarrollo)</ToolTip>
<Default>0</Default>
<Function>
</Function>
<Type>System.Int32</Type>
</Object>
<Object Editable="true">
<ID>REVISION</ID>
<ToolTip>Version REVISION (verifique la versión de la aplicación en desarrollo)</ToolTip>
<Default>0</Default>
<Function>
</Function>
<Type>System.Int32</Type>
</Object>
<Object Editable="true">
<ID>REF</ID>
<ToolTip>Escriba una referencia sobre tema de la modificación.</ToolTip>
<Default>REFERENCIA</Default>
<Function>
</Function>
<Type>System.String</Type>
</Object>
<Object Editable="true">
<ID>INFO</ID>
<ToolTip>Presione Ctrl+Shift+D para ejecutar la macro que introduce la referencia de fecha y usuario.</ToolTip>
<Default>Fecha - Nombre (Macro: Ctrl+Shift+D)</Default>
<Function>
</Function>
<Type>System.Int32</Type>
</Object>
</Declarations>
<Code Language="csharp">
<![CDATA[
/* MODIF v $MAJOR$.$MINOR$.$BUILD$.$REVISION$ - $REF$ - $INFO$
*
*
*/
$end$]]>
</Code>
</Snippet>
</CodeSnippet>
</CodeSnippets>
Probar el snippet
En algún lugar del código sobre el que estemos trabajando, escribir modif. A medida que se va escribiendo, IntelliSense hará aparecer la persiana donde se despliegan los Snippets. Aquí debería aparecer el nuestro, con su correspondiente descripción:
Al estar seleccionado, presionar TAB 2 veces. El snippet escribirá el código que tiene definido. El cursor se posiciona en el primer dígito de versión:
Presionando TAB repetidas veces, el cursor salta por los textos resaltados, para poder editarlos. Falta ahora disponer de la macro que introduzca automáticamente la fecha y el autor del comentario.
Paso 2: Crear la macro.
En Visual Studio, hacer lo siguiente:
- Presionar Alt + F8 (o ir a Tools > Macros Explorer).
- Hacer click derecho en Modules (debajo de MyMacros) y seleccionar Add New Macro.
- Inmediatamente debajo de Public Module Module1, pegar el siguiente código:
' Esta macro introduce fecha, hora y el usuario logueado en la posición del cursor.
' Está preparada para funcionar con el snippet de comentarios de modificación de código.
' 11/03/2010 - Marcelo Calderón Orrequia
Sub Date_User()
Dim _text As String
Dim _text0 As String
DTE.ActiveDocument.Selection.Text = "" ' elimina el texto donde se reemplazará la primer parte de los datos
DTE.ActiveDocument.Selection.StartOfLine(vsStartOfLineOptions.vsStartOfLineOptionsFirstText, True)
_text = DTE.ActiveDocument.Selection.Text
DTE.ActiveDocument.Selection.EndOfLine()
If InStr(_text, "MODIF v") > 0 Then ' para el snippet MODIF
DTE.ActiveDocument.Selection.Text = String.Format("{0:d} ({1})", Now, System.Environment.UserName)
DTE.ActiveDocument.Selection.LineDown()
DTE.ActiveDocument.Selection.EndOfLine()
DTE.ActiveDocument.Selection.LineDown(2)
DTE.ActiveDocument.Selection.Text = String.Format("{0:D} por {1} a las {0:HH}:{0:mm}:{0:ss}", Now, System.Environment.UserName)
DTE.ActiveDocument.Selection.Indent()
DTE.ActiveDocument.Selection.LineUp()
DTE.ActiveDocument.Selection.EndOfLine()
Else ' para el snippet NOTAS (ocualquier otro)
DTE.ActiveDocument.Selection.Text = String.Format("{0:d} ({1})", Now, System.Environment.UserName)
DTE.ActiveDocument.Selection.LineDown()
DTE.ActiveDocument.Selection.EndOfLine()
DTE.ActiveDocument.Selection.CharLeft(False, 2)
DTE.ActiveDocument.Selection.Indent()
DTE.ActiveDocument.Selection.Text = String.Format("{0:D} por {1} a las {0:HH}:{0:mm}:{0:ss}", Now, System.Environment.UserName)
DTE.ActiveDocument.Selection.NewLine()
DTE.ActiveDocument.Selection.Text = "*"
DTE.ActiveDocument.Selection.NewLine()
DTE.ActiveDocument.Selection.LineUp()
DTE.ActiveDocument.Selection.CharRight(False, 1)
DTE.ActiveDocument.Selection.Indent()
End If
End Sub
Probar la macro
Para probar el funcionamiento de la macro, hacer lo siguiente:
- Ejecutar nuestro snippet escribiendo modif y presionar TAB hasta que quede seleccionado el texto final (donde dice "Fecha - Nombre (Macro: Ctrl+Shift+D").
- Abrir la ventana Macro Explorer (Alt+F8, o bien Tools > Macros > Macro Explorer).
- Ejecutar la macro (clic derecho sobre Date_User). La imagen da una idea de cómo:
 |
| Ejecutando la macro |
Si todo fue bien, deberíamos obtener el comentario con el nombre del autor y la fecha. El cursor queda automáticamente posicionado al final de la primer línea (indicado con la flecha roja) para permitir la rápida introducción del comentario en si, para lo que solo hay que presionar ENTER y comenzar a escribir.
Paso 3: Configurar Visual Studio
Para este ejemplo vamos a asignar la combinación de teclas Ctrl+Shift+D para que se ejecute la macro en la poisición en que se encuentre el cursor. La macro identifica el texto "MODIF" y reacciona en función de ello.
Para asignar las teclas, en Visual Studio:
- Ir a Tools > Options > Environment > Keyboard
- Buscar en Commands y seleccionar Macros.MyMacros.Module1.Date_User
- Ubicarse en Press shortcut keys
- Presionar las teclas Ctrl+Shift+D
- Hacer clic en Assign y luego OK
 |
| Configuración de la combinación de teclas para la macro |
Ahora, una vez posicionados en el texto que generó el snippet (donde dice que se presione Ctrl+Shift+D), al presionar esa combinación de teclas debería ejecutarse la macro.
Vamos a ahora a registrar el identificador en la lista de tareas, para ver los comentarios en la ventana Task List:
- Ir a Tools > Options > Environment > Task List
- Ubicarse en el cuadro Name:
- Escribir MODIF
- Presionar Add y luego OK
 |
| Agregando un identificador de tarea |
Probar todo
- En algún lugar de nuestro código, escribir modif y presionar TAB dos veces para generar el comentario.
- Escribir el número mayor de la versión (el primero) y presionar TAB para saltar al segundo. Hacerlo para cada uno de los números de la versión.
- Presionar TAB para hacer foco en "REFERENCIA" y escribir algo como BUG, CAMBIO, o cualquier otra cosa que premita identificar fácilmente de qué se trata el comentario.
- Saltar (con TAB) a la parte final, y presionar Ctrl+Shift+D.
- Presionar ENTER
- Escribir el texto del comentario.
- Repetir esto varias veces en distintas partes del código de la aplicación poniendo distintos números de versión en cada caso.
- Abrir la ventana de lista de tareas (Ctrl+Alt+K, o desde View > Task List) y seleccionar Comments
- Hacer clic en el encabezado de la lista (Description) para ordenar la lista. Se verán los comentarios MODIF ordenados por número de versión. Si los números de versión son coherentes, también quedarán ordenados cronológicamente.
- Hacer doble clic en cualquiera de los items de la lista para ir directo al código.
 |
| Seleccionando Comments en Task List |
Como consejo final, no está de más tener en cuenta que cuando se escriban las descripciones en REFERENCIAS, conviene tener definidas palabras clave que todo el mundo utilice, como BUG, NUEVO, CAMBIO, etc. Así será mucho más fácil identificar en el listado de qué se trata el asunto del comentario.
Conclusión
De más está comentar al valor agregado que le da toda buena documentación a un proyecto. Independientemente de la metodología utilizada, es sabido que mucho no siempre significa mejor.
Si bien esta práctica parece algo trivial, me parece muy útil acostumbrar al equipo de trabajo a este tipo de rutinas, sumadas o otras buenas prácticas.
Creo que vale la pena tomarse un rato para poner esto en funcionamiento, porque así mucho más fácil conocer e identificar los cambios realizados, cuándo y por quién; al menos en una primera instancia.
Espero sirva de ayuda para mejorar la calidad del trabajo.
Recursos
Los archivos para el ejemplo del video se pueden bajar de aquí. (hacer clic en "Archivo > Descargar" para bajarlo completo).
