Blog

Uso de los enlaces de documentación con Sensei

Alan Richardson
Publicado Nov 09, 2020

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

Descubra cómo Sensei puede ayudar a incorporar a los desarrolladores y a adoptar nuevas bibliotecas.

¿Quiere saber más?

Alan Richardson cuenta con más de veinte años de experiencia profesional en TI, trabajando como desarrollador y en todos los niveles de la jerarquía de pruebas, desde probador hasta jefe de pruebas. Jefe de Relaciones con los Desarrolladores en Secure Code Warrior, trabaja directamente con los equipos, para mejorar el desarrollo de un código seguro de calidad. Alan es autor de cuatro libros, entre ellos "Dear Evil Tester" y "Java For Testers". Alan también ha creado una formación en línea courses para ayudar a la gente a aprender las pruebas técnicas de la web y Selenium WebDriver con Java. Alan publica sus escritos y vídeos de formación en SeleniumSimplified.com, EvilTester.com, JavaForTesters.com, y CompendiumDev.co.uk.

Secure Code Warrior está a disposición de su organización para ayudarle a proteger el código a lo largo de todo el ciclo de vida de desarrollo de software y crear una cultura en la que la ciberseguridad sea una prioridad. Tanto si es director de AppSec, desarrollador, CISO o cualquier persona implicada en la seguridad, podemos ayudar a su organización a reducir los riesgos asociados a un código inseguro.

Reservar una demostración
Compartir en:
Autor
Alan Richardson
Publicado Nov 09, 2020

Alan Richardson cuenta con más de veinte años de experiencia profesional en TI, trabajando como desarrollador y en todos los niveles de la jerarquía de pruebas, desde probador hasta jefe de pruebas. Jefe de Relaciones con los Desarrolladores en Secure Code Warrior, trabaja directamente con los equipos, para mejorar el desarrollo de un código seguro de calidad. Alan es autor de cuatro libros, entre ellos "Dear Evil Tester" y "Java For Testers". Alan también ha creado una formación en línea courses para ayudar a la gente a aprender las pruebas técnicas de la web y Selenium WebDriver con Java. Alan publica sus escritos y vídeos de formación en SeleniumSimplified.com, EvilTester.com, JavaForTesters.com, y CompendiumDev.co.uk.

Compartir en:

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

Rellene el siguiente formulario para descargar el informe

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.

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

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

 


Acceso a recursos

Haga clic en el siguiente enlace y descargue el PDF de este recurso.

Secure Code Warrior está a disposición de su organización para ayudarle a proteger el código a lo largo de todo el ciclo de vida de desarrollo de software y crear una cultura en la que la ciberseguridad sea una prioridad. Tanto si es director de AppSec, desarrollador, CISO o cualquier persona implicada en la seguridad, podemos ayudar a su organización a reducir los riesgos asociados a un código inseguro.

Ver el informeReservar una demostración
Descargar PDF
Ver recurso
Compartir en:
¿Quiere saber más?

Compartir en:
Autor
Alan Richardson
Publicado Nov 09, 2020

Alan Richardson cuenta con más de veinte años de experiencia profesional en TI, trabajando como desarrollador y en todos los niveles de la jerarquía de pruebas, desde probador hasta jefe de pruebas. Jefe de Relaciones con los Desarrolladores en Secure Code Warrior, trabaja directamente con los equipos, para mejorar el desarrollo de un código seguro de calidad. Alan es autor de cuatro libros, entre ellos "Dear Evil Tester" y "Java For Testers". Alan también ha creado una formación en línea courses para ayudar a la gente a aprender las pruebas técnicas de la web y Selenium WebDriver con Java. Alan publica sus escritos y vídeos de formación en SeleniumSimplified.com, EvilTester.com, JavaForTesters.com, y CompendiumDev.co.uk.

Compartir en:

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

 


Índice

Descargar PDF
Ver recurso
¿Quiere saber más?

Alan Richardson cuenta con más de veinte años de experiencia profesional en TI, trabajando como desarrollador y en todos los niveles de la jerarquía de pruebas, desde probador hasta jefe de pruebas. Jefe de Relaciones con los Desarrolladores en Secure Code Warrior, trabaja directamente con los equipos, para mejorar el desarrollo de un código seguro de calidad. Alan es autor de cuatro libros, entre ellos "Dear Evil Tester" y "Java For Testers". Alan también ha creado una formación en línea courses para ayudar a la gente a aprender las pruebas técnicas de la web y Selenium WebDriver con Java. Alan publica sus escritos y vídeos de formación en SeleniumSimplified.com, EvilTester.com, JavaForTesters.com, y CompendiumDev.co.uk.

Secure Code Warrior está a disposición de su organización para ayudarle a proteger el código a lo largo de todo el ciclo de vida de desarrollo de software y crear una cultura en la que la ciberseguridad sea una prioridad. Tanto si es director de AppSec, desarrollador, CISO o cualquier persona implicada en la seguridad, podemos ayudar a su organización a reducir los riesgos asociados a un código inseguro.

Reservar una demostraciónDescargar
Compartir en:
Centro de recursos

Recursos para empezar

Más entradas
Centro de recursos

Recursos para empezar

Más entradas