Uso de los enlaces de documentación con Sensei

Publicado Nov 09, 2020
por Alan Richardson
ESTUDIO DE CASO

Uso de los enlaces de documentación con Sensei

Publicado Nov 09, 2020
por Alan Richardson
Ver recurso
Ver recurso

Una de las dificultades de aprender una nueva biblioteca, o de compartir prácticas acordadas en nuestro equipo, es documentar y crear ejemplos.

A menudo creamos pequeños proyectos de ejemplo, pero no los tenemos abiertos cuando trabajamos con el código real.

A menudo he pensado que sería estupendo tener la posibilidad de enlazar con nuestros ejemplos, o con ejemplos en línea y poder ir a una URL para obtener más explicaciones cuando sea necesario.

Con Java, tenemos los comentarios JavaDoc, que pueden tener una anotación see:

/**
 * @see <a href="https://junit.org/junit5/docs/current/user-guide/#writing-tests-annotations">Junit 5 Annotation docs</a>
 */

Este tipo de JavaDoc en las librerías de terceros es una gran ayuda porque podemos utilizar la funcionalidad de documentación rápida en IntelliJ para tener acceso a ejemplos más detallados.

Pero todos sabemos que los comentarios no se actualizan con la misma frecuencia que el código, y el mantenimiento de la presencia en la web suele estar desconectado del mantenimiento de la biblioteca y a veces lo realiza un equipo totalmente distinto.

Cómo ayuda Sensei

Sensei proporciona la capacidad de coincidir en las anotaciones de la biblioteca y los métodos para proporcionar enlaces a la documentación de forma larga en un wiki o un sitio tutorial de terceros.

Como ejemplo, estoy usando la anotación @Test de JUnit.

El JavaDoc es muy detallado, y la vista de documentación rápida explica cómo utilizar la anotación.

Pero la documentación oficial en el sitio web suele ser más fácil de leer y tiene más ejemplos.

Cuando un equipo empieza a aprender una biblioteca, tener un conjunto de tutoriales recomendados, puede ser muy útil.

Sensei tiene una acción goto que podemos utilizar para abrir una URL, lo que nos permite enlazar con sitios externos y ejemplos para la documentación que, como equipo, encontramos útil.

Implementación de la URL Goto

Para implementar esto crearía una búsqueda que coincida con la anotación @Test de Junit.

search:
   annotation:
    owner:
      method: {}
    type: "org.junit.jupiter.api.Test"


Y luego añadiría acciones goto para cada una de las URLs que considere útiles.

Por ejemplo

El ejemplo siguiente crearía una única acción de anotaciones JUnit (learn) que abriría ambas URLs en un navegador al mismo tiempo.

availableFixes:
- name: "Learn about JUnit Annotations"
actions:
- goto:
type: "URL"
value: "https://junit.org/junit5/docs/current/user-guide/#writing-tests-annotations"=
- goto:
type: "URL"
valor: "https://junit.org/junit5/docs/current/user-guide/#writing-tests-classes-and-methods"

Y cuando lo activo en IntelliJ con Alt+Enter veo el menú contextual que puedo seleccionar para saltar a la documentación.


Acciones múltiples

Podría optar por tener múltiples Acciones para que cada URL o tutorial tenga su propia opción en el menú emergente alt+enter Quick Fix.

Por ejemplo, para la anotación @Parameterized, podría querer enlazar con la documentación oficial y un conjunto de código de ejemplo en línea.

Simplemente crearía una receta que busque la anotación:

search:
  annotation:
    owner:
      method: {}
    type: "org.junit.jupiter.params.ParameterizedTest"


Y enlaces a los sitios que he identificado como útiles:

availableFixes:
- name: "JUnit Annotations (learn)"
actions:
- goto:
type: "URL"
value: "https://junit.org/junit5/docs/current/user-guide/#writing-tests-annotations"
- name: "¿Qué es una prueba JUnit? (learn)"
actions:
- goto:
type: "URL"
value: "https://junit.org/junit5/docs/current/user-guide/#writing-tests-classes-and-methods"


Ambos enlaces aparecerán entonces en el cuadro de diálogo emergente.

¿Quién se beneficiaría?

Me habría resultado útil a la hora de utilizar y aprender las bibliotecas, sobre todo al dirigir equipos y ayudarles a adoptar una nueva biblioteca.

Esto también podría beneficiar a los equipos que crean bibliotecas, al crear un conjunto estándar de recetas de documentación para ayudar a guiar a la gente a través de la adopción de la biblioteca o de nuevas características en la biblioteca.

Esto sería especialmente útil si el mantenimiento del código y el de la documentación son realizados por equipos diferentes.

Puedes instalar Sensei desde IntelliJ usando `preferences > plugins` (sólo busca "sensei secure code").

Todo el código de esta entrada del blog está en Github en el módulo junitexamples en https://github.com/SecureCodeWarrior/sensei-blog-examples

 


Ver recurso
Ver recurso

Autor

Alan Richardson

¿Quieres más?

Sumérjase en nuestras últimas ideas sobre codificación segura en el blog.

Nuestra amplia biblioteca de recursos tiene como objetivo potenciar el enfoque humano de la mejora de la codificación segura.

Ver blog
¿Quieres más?

Obtenga las últimas investigaciones sobre la seguridad impulsada por los desarrolladores

Nuestra amplia biblioteca de recursos está repleta de recursos útiles, desde libros blancos hasta seminarios web, que le ayudarán a iniciarse en la codificación segura orientada a los desarrolladores. Explórela ahora.

Centro de recursos

Uso de los enlaces de documentación con Sensei

Publicado Nov 09, 2020
Por Alan Richardson

Una de las dificultades de aprender una nueva biblioteca, o de compartir prácticas acordadas en nuestro equipo, es documentar y crear ejemplos.

A menudo creamos pequeños proyectos de ejemplo, pero no los tenemos abiertos cuando trabajamos con el código real.

A menudo he pensado que sería estupendo tener la posibilidad de enlazar con nuestros ejemplos, o con ejemplos en línea y poder ir a una URL para obtener más explicaciones cuando sea necesario.

Con Java, tenemos los comentarios JavaDoc, que pueden tener una anotación see:

/**
 * @see <a href="https://junit.org/junit5/docs/current/user-guide/#writing-tests-annotations">Junit 5 Annotation docs</a>
 */

Este tipo de JavaDoc en las librerías de terceros es una gran ayuda porque podemos utilizar la funcionalidad de documentación rápida en IntelliJ para tener acceso a ejemplos más detallados.

Pero todos sabemos que los comentarios no se actualizan con la misma frecuencia que el código, y el mantenimiento de la presencia en la web suele estar desconectado del mantenimiento de la biblioteca y a veces lo realiza un equipo totalmente distinto.

Cómo ayuda Sensei

Sensei proporciona la capacidad de coincidir en las anotaciones de la biblioteca y los métodos para proporcionar enlaces a la documentación de forma larga en un wiki o un sitio tutorial de terceros.

Como ejemplo, estoy usando la anotación @Test de JUnit.

El JavaDoc es muy detallado, y la vista de documentación rápida explica cómo utilizar la anotación.

Pero la documentación oficial en el sitio web suele ser más fácil de leer y tiene más ejemplos.

Cuando un equipo empieza a aprender una biblioteca, tener un conjunto de tutoriales recomendados, puede ser muy útil.

Sensei tiene una acción goto que podemos utilizar para abrir una URL, lo que nos permite enlazar con sitios externos y ejemplos para la documentación que, como equipo, encontramos útil.

Implementación de la URL Goto

Para implementar esto crearía una búsqueda que coincida con la anotación @Test de Junit.

search:
   annotation:
    owner:
      method: {}
    type: "org.junit.jupiter.api.Test"


Y luego añadiría acciones goto para cada una de las URLs que considere útiles.

Por ejemplo

El ejemplo siguiente crearía una única acción de anotaciones JUnit (learn) que abriría ambas URLs en un navegador al mismo tiempo.

availableFixes:
- name: "Learn about JUnit Annotations"
actions:
- goto:
type: "URL"
value: "https://junit.org/junit5/docs/current/user-guide/#writing-tests-annotations"=
- goto:
type: "URL"
valor: "https://junit.org/junit5/docs/current/user-guide/#writing-tests-classes-and-methods"

Y cuando lo activo en IntelliJ con Alt+Enter veo el menú contextual que puedo seleccionar para saltar a la documentación.


Acciones múltiples

Podría optar por tener múltiples Acciones para que cada URL o tutorial tenga su propia opción en el menú emergente alt+enter Quick Fix.

Por ejemplo, para la anotación @Parameterized, podría querer enlazar con la documentación oficial y un conjunto de código de ejemplo en línea.

Simplemente crearía una receta que busque la anotación:

search:
  annotation:
    owner:
      method: {}
    type: "org.junit.jupiter.params.ParameterizedTest"


Y enlaces a los sitios que he identificado como útiles:

availableFixes:
- name: "JUnit Annotations (learn)"
actions:
- goto:
type: "URL"
value: "https://junit.org/junit5/docs/current/user-guide/#writing-tests-annotations"
- name: "¿Qué es una prueba JUnit? (learn)"
actions:
- goto:
type: "URL"
value: "https://junit.org/junit5/docs/current/user-guide/#writing-tests-classes-and-methods"


Ambos enlaces aparecerán entonces en el cuadro de diálogo emergente.

¿Quién se beneficiaría?

Me habría resultado útil a la hora de utilizar y aprender las bibliotecas, sobre todo al dirigir equipos y ayudarles a adoptar una nueva biblioteca.

Esto también podría beneficiar a los equipos que crean bibliotecas, al crear un conjunto estándar de recetas de documentación para ayudar a guiar a la gente a través de la adopción de la biblioteca o de nuevas características en la biblioteca.

Esto sería especialmente útil si el mantenimiento del código y el de la documentación son realizados por equipos diferentes.

Puedes instalar Sensei desde IntelliJ usando `preferences > plugins` (sólo busca "sensei secure code").

Todo el código de esta entrada del blog está en Github en el módulo junitexamples en https://github.com/SecureCodeWarrior/sensei-blog-examples

 


Nos gustaría contar con su permiso para enviarle información sobre nuestros productos y/o temas relacionados con la codificación segura. Siempre trataremos sus datos personales con el máximo cuidado y nunca los venderemos a otras empresas con fines de marketing.

Para enviar el formulario, habilite las cookies "Analytics". Siéntase libre de desactivarlas de nuevo una vez que haya terminado.