Pausa para el café #79. Diez errores que cometen los desarrolladores de Java que les impiden alcanzar el éxito. Una guía para desarrolladores para escribir comentarios de código significativos

Diez errores que cometen los desarrolladores de Java que impiden su éxito

Fuente: Dev.to Según mi experiencia, he compilado una lista de 10 errores que cometen los desarrolladores y que les impiden alcanzar el éxito:

1. No escribas pruebas unitarias

Los desarrolladores que no escriben pruebas unitarias cometen más errores en su código. Esto conduce a la inestabilidad del producto y a la insatisfacción del cliente.

2. No verifican el código manualmente

Incluso si cubre completamente su código con pruebas unitarias, todavía existe la posibilidad de que se haya perdido algo. Siempre se recomienda probar manualmente su código antes de enviarlo para su revisión. De esta forma podrá detectar errores en la etapa de desarrollo.

3. Piensan: "Esto nunca sucederá".

Los desarrolladores a menudo cometen errores al escribir código nuevo, pensando que ciertos escenarios nunca sucederán. Al final resulta que están equivocados. Manejar todos los escenarios donde se puede ejecutar código. Los métodos de programación defensiva le ayudarán con esto.

4. No recibas comentarios

Solicite periódicamente comentarios de otros desarrolladores y usuarios. Comparte tu opinión con tus colegas.

5. No verifican la funcionalidad del código.

A menudo los desarrolladores escriben su código, pero no comprueban su funcionalidad. Como resultado, cuando el código llega a producción, crea varios problemas.

6. Escriba un código de procedimiento largo

Es muy fácil escribir métodos largos con mucha lógica. Al hacer esto, los programadores implementan la misma lógica en muchos lugares. Los proyectos con una cantidad significativa de métodos pequeños tienen una reutilización de código mucho mejor y son mucho más fáciles de mantener.

7. No conocen las herramientas

Las herramientas son una extensión de tus manos. Cuanto mejor los conozcas, más productivo serás. Debes estar muy familiarizado con el IDE que estás utilizando. Aprende comandos rápidos, siempre hay comandos que te ayudarán a ser aún más productivo. En IntelliJ IDEA, estos son Sonar Lint, Spot bugs y Code Metrics.

8. Ignora los problemas en el código.

Los desarrolladores que trabajan en los productos más exitosos cambian constantemente el código. No tengas miedo de refactorizar tu código. Si su código se prueba unitariamente, hay pocas posibilidades de regresión. Los desarrolladores suelen ignorar el código problemático. Como desarrollador, usted es responsable de mantener la aplicación en buenas condiciones. Por este motivo, solucione cualquier problema que encuentre.

9. Codifican sin darse cuenta de las consecuencias.

Los desarrolladores NUNCA deben realizar cambios en el código y lanzarlo a producción sin comprender las consecuencias. El código puede producir resultados correctos para los valores de prueba dados. Sin embargo, puede haber escenarios en los que esto podría conducir a resultados impredecibles y crear problemas graves. La codificación "impredecible" suele ocurrir cuando los desarrolladores utilizan funciones de bibliotecas que no comprenden completamente. Esto también puede suceder cuando un desarrollador soluciona un problema sin comprender la solución.

10. No pidas ayuda

Los desarrolladores no son personas muy sociables. Les gusta resolver problemas por sí solos. Pero la era en la que un desarrollador creaba un producto de principio a fin ha terminado. El desarrollo de software es una actividad de equipo. Cuando encuentre un problema mientras programa, intente resolverlo usted mismo. Pero no pierdas demasiado tiempo si no encuentras una solución. Existe una alta probabilidad de que algunos de sus colegas ya hayan encontrado el mismo problema y conozcan la solución. Esto ahorrará tiempo y aumentará la productividad.

Una guía para desarrolladores para escribir comentarios de código significativos

Fuente: Stepsize En la mayoría de los casos, no eres el único que trabaja en el mismo proyecto o código base. Esto significa que otras personas deben entender su código. Esto también es válido para los comentarios de código. Los desarrolladores suelen escribir comentarios "rápidos y sucios" sin mucho contexto, lo que deja a sus colegas confundidos acerca de lo que el autor intentaba decir. Esta es una mala práctica y crea más confusión que claridad. Tener comentarios de código claros ayuda a otros desarrolladores. Un comentario de código que describe una función, su fundamento, entrada y salida acelera el proceso de aprendizaje para otros desarrolladores. Por otro lado, los comentarios de código nos llevan a la pregunta: ¿merece la pena escribirlos? Un grupo importante de desarrolladores se opone a escribir comentarios de código. La razón es que el código, en su opinión, se explica por sí solo. Si otro desarrollador no puede entender el propósito de su código al mirarlo, entonces es un código incorrecto. Quizás esto sea cierto. Pero piense en el pequeño esfuerzo que se requiere para comentar el código y los beneficios potenciales que aporta. Los comentarios de código son importantes para acelerar el proceso de incorporación de cualquier desarrollador, especialmente los más jóvenes. Veamos los diferentes tipos de comentarios de código.

1. Comentarios a la documentación.

El objetivo principal de dichos comentarios es aclarar rápidamente el propósito de un archivo o componente. En lugar de leer el código completo de un componente para comprender lo que hace, puede agregar un comentario de código en la parte superior del archivo "índice". Esto ayudará a explicar qué hace este componente. No soy un gran admirador de este tipo de comentarios porque satura un poco el código. Creo que este tipo de comentarios de arquitectura deberían estar en su documentación interna, donde puede mantener y discutir de manera centralizada la arquitectura de su proyecto. Sin embargo, los proyectos de código abierto realmente los necesitan.

2. Comentarios sobre funciones.

Este es el tipo de comentario más útil. Describen el propósito de la función, sus parámetros y su salida.

/**
 * @desc Creates a welcome message
 */
function sayHello(name) {
    return `Hello ${name}`;
}

3. Comentarios lógicos.

Estos son comentarios dentro de funciones para aclarar rutas de código complejas. Como habrás adivinado, la presencia de este tipo de comentarios indica que tu código es demasiado complejo. Además, los comentarios lógicos suelen contener demasiada información detallada. El nivel de detalle creará más caos y reducirá la legibilidad de su código. A continuación se muestra un ejemplo de un comentario de código demasiado detallado.

let date = new Date(); // store today's date to calculate the elapsed time

Comentario de código: 4 mejores prácticas para comentar

1. Utilice etiquetas o anotaciones de código

Muchos lenguajes de programación definen estándares para comentar código. Java usa Javadoc , mientras que JavaScript usa el sistema de comentarios de código JSDoc , que es compatible con muchas herramientas de documentación. Para las funciones debe incluir las siguientes etiquetas de código:

• @desc - descripción de su función
• @param: todos los parámetros de entrada que acepta la función. Asegúrese de especificar los tipos de entrada.
• @returns: salida devuelta. Asegúrese de especificar el tipo de salida.
• @throws es el tipo de error que puede arrojar la función.
• @ejemplo: uno o más ejemplos que muestran la entrada y el resultado esperado.

A continuación se muestra un código Lodash de ejemplo para la función de fragmento .

/**
 * Creates an array of elements split into groups the length of `size`.
 * If `array` can't be split evenly, the final chunk will be the remaining
 * elements.
 *
 * @since 3.0.0
 * @category Array
 * @param {Array} array The array to process.
 * @param {number} [size=1] The length of each chunk
 * @returns {Array} Returns the new array of chunks.
 * @example
 *
 * chunk(['a', 'b', 'c', 'd'], 2)
 * // => [['a', 'b'], ['c', 'd']]
 *
 * chunk(['a', 'b', 'c', 'd'], 3)
 * // => [['a', 'b', 'c'], ['d']]
 */
function chunk(array, size = 1) {
  // logic
}

2. Explica el motivo de tus acciones.

Muchos desarrolladores utilizan comentarios para describir lo que hace su código. Al hacerlo, asegúrese de incluir por qué creó una característica o componente en particular. Esta información se llama contexto. El contexto es importante para brindar a los desarrolladores más información sobre las decisiones de diseño detrás de una característica o componente. El contexto es fundamental cuando otros desarrolladores quieren realizar cambios en su característica o componente. A continuación puede ver un mal ejemplo de código de comentario sin contexto.

/**
 * Sets the label property of a new form.
 *
 * @param label text for label of form
 */
function setFormLabel(label) {
    // logic
}

3. No enlace a otros documentos o comentarios

No se recomienda vincular a otros comentarios de código o documentos internos que expliquen una característica o componente.

/**
 * Sets the label property of a new form.
 *
 * @see {@link https://myinternaldocument.com}
 */
function setFormLabel(label) {
    // logic
}

4. Escriba comentarios mientras codifica

Esto puede parecer obvio, pero muchos desarrolladores (incluido yo mismo) descuidan esta regla. Dejar comentarios para más tarde es malo porque puedes olvidar parte de la lógica que escribiste, lo que dará lugar a comentarios de código de menor calidad. Esto es especialmente cierto si ha estado trabajando en la misma solicitud de extracción durante varios días. Es mejor escribir comentarios cuando acaba de terminar una función o módulo. Recuerde mantener los comentarios del código lo más breves posible. No es necesario dedicar más tiempo a escribir comentarios que a escribir el código en sí.