Liberar la productividad del desarrollador: ¿Aprender sobre el código “a nivel de documento”?

Un chiste que perdura en Internet:

Las cuatro cosas que más odian los programadores:

escribe notas

escribir documento

Otros no escriben comentarios.

Otros no escriben documentos.

Hoy comenzaremos con documentos que los desarrolladores "no soportan y de los que no pueden deshacerse".

1. La importancia de la documentación

La documentación de alta calidad es una herramienta eficaz para registrar y comunicar información, ayudando a las personas a comprender y cumplir normas, políticas y procedimientos. También sirven como referencia y evidencia para apoyar la toma de decisiones y la resolución de problemas. A través de registros escritos, las personas pueden preservar y compartir conocimientos durante períodos de tiempo más largos. Además, una buena documentación mejora la eficiencia del trabajo y reduce los malentendidos y errores. En resumen, la documentación juega un papel importante en la vida personal y laboral y es crucial para la sostenibilidad de una organización.

La documentación de alta calidad tiene muchos beneficios para una organización o equipo.

En primer lugar, la documentación puede hacer que el código y la API sean más fáciles de entender, lo que reduce la posibilidad de errores.

En segundo lugar, la documentación permite a los miembros del equipo centrarse más en sus objetivos y resolver problemas rápidamente.

Además, la documentación también facilita algunas tareas manuales.

Además, si se unen nuevos miembros, la documentación puede ayudarlos a integrarse al equipo más rápidamente.

La redacción de documentación conlleva un grave retraso en los ingresos. A diferencia de las pruebas, ejecutar un caso de prueba puede determinar inmediatamente si es correcto o no, y su valor se refleja inmediatamente.
Al escribir un documento, su importancia se hará evidente con el tiempo. Puede que sólo lo escribas una vez, pero será leído muchas veces, cientos o incluso miles de veces.

Un documento excelente puede responder las siguientes preguntas en el futuro:
• ¿ Por qué se tomó tal decisión en ese momento?
• ¿ Por qué el código se implementa de esta manera?
• ¿ Qué conceptos se están incorporando a este proyecto?
•...
Escribir documentación también tiene enormes beneficios para el propio autor:
• Ayudarle a estandarizar el diseño de API: Escribir documentación es un proceso de revisión de la API. Escribir documentación puede hacerle pensar si el diseño de API es razonable y completo. Si no puede describir con precisión la API con palabras, entonces el diseño actual de la API no es razonable.
• La documentación también es otra forma de presentar el código: por ejemplo, si vuelve a ver el código que escribió dos años después, siempre que haya comentarios y documentación, podrá comprenderlo rápidamente.
• Mejorar la profesionalidad del código: Todos tenemos la sensación de que mientras la API tenga la documentación completa, es una API bien diseñada. Aunque esta sensación no sea del todo cierta, ambos son inseparables: para muchas personas, la integridad de la documentación se ha convertido también en un indicador de la profesionalidad de un producto.
• Evite interrupciones innecesarias con preguntas repetidas: algunas preguntas se pueden registrar directamente en el documento, de modo que cuando alguien venga a preguntarle, pueda permitirle ver el documento directamente sin tener que volver a explicarlo. .

2. ¿Por qué a la mayoría de la gente no le gusta escribir documentos?

¿Por qué mucha gente no ha desarrollado el hábito de escribir documentos? Después de todo, la documentación se vuelve muy importante después de que el problema lleva mucho tiempo resuelto.

Además de las razones del retraso en los ingresos por documentos mencionadas anteriormente, también existen los siguientes factores:

•Muchos ingenieros están acostumbrados a separar codificación y escritura, no sólo en su trabajo, sino también en su pensamiento de que son dos tareas completamente ajenas, lo que lleva a muchas personas a centrarse más en el código e ignorar la importancia de la documentación.

•Muchos ingenieros también piensan que no son buenos escribiendo, por lo que simplemente optan por no escribir. Sin embargo, esto es sólo una excusa para ser vagos. De hecho, escribir documentos no requiere una retórica magnífica ni un lenguaje vívido, sólo es necesario explicar el problema con claridad.

•A veces, la imposibilidad de utilizar herramientas también tendrá un impacto en la redacción de documentos. Sin una herramienta de redacción de calidad que integre la redacción de documentos en el flujo de trabajo de desarrollo, la carga de redacción aumenta.

•La mayoría de la gente piensa que escribir documentos es otra carga de trabajo. ¡Ya no tengo tiempo para escribir código, y mucho menos escribir documentación! En realidad, este es un concepto equivocado. Si bien escribir documentación puede requerir cierta inversión inicial, puede reducir significativamente los costos posteriores de mantenimiento del código. Creo que todo el mundo puede entender el principio de afilar el cuchillo antes de cortar leña.

3. Herramientas de IA para ayudar

Si existe una herramienta de programación de IA que puede generar código "a nivel de documento", ¿puede resolver el gran problema de la gran mayoría de los desarrolladores que no pueden o no quieren escribir comentarios y documentos?

Como parte importante del robot de software SoFlu de Feisuan, el generador de IA FuncGPT admite la creación de todo tipo de funciones. El generador de IA FuncGPT utiliza lenguaje natural para describir los requisitos de las funciones de Java y genera códigos de funciones de Java de alta calidad y muy legibles en tiempo real. El código generado se puede copiar directamente a IDEA o importar a la biblioteca de funciones de la herramienta de desarrollo totalmente automática de Java con un solo clic.

FuncGPT (Funciones) puede resolver muy bien los siguientes problemas de código:

1. Especificaciones del código: genere códigos de función que cumplan con la sintaxis y las especificaciones del código de Java, el código generado será más fácil de leer y comprender.

2. Reutilización de código: el código de función generado tenderá a utilizar las mejores prácticas reutilizables. Puede reducir el código redundante y mejorar la capacidad de mantenimiento del código.

3. Comentarios de código: el código generado contendrá comentarios de código claros para ayudar a los ingenieros de desarrollo a comprender el propósito y la entrada y salida de la función. Los buenos comentarios son muy importantes para el mantenimiento posterior.

4. Estructura del código : el código generado tenderá a utilizar una buena estructura de código y evitará funciones demasiado largas y anidamientos excesivos. Esto ayuda a mejorar la legibilidad y el mantenimiento del código.

5. Reduzca significativamente el trabajo de depuración de código: el código generado se ha sometido a una capacitación conjunta a gran escala y puede generar código más preciso y estable, reduciendo así el trabajo de depuración causado por errores de código.

Tomemos como ejemplo el uso de funciones Java en el sistema de gestión de tareas para implementar la función de calcular el tiempo restante de una tarea:

// Nombre de clase: DateUtils

// Nombre de la función: calcularDateDifference

// Función: Calcular el número de días de diferencia entre dos fechas

// paquete de dependencia POM :

// <dependencia>

// <groupId>hora-joda</groupId>

// <artifactId>hora-joda</artifactId>

// <versión>2.10.10</versión>

// </dependencia>

importar org.joda.time.DateTime;

importar org.joda.time.Days;

clase pública DateUtils {

    /**

     * Calcular el número de días de diferencia entre dos fechas.

     * @param startTime hora de inicio

     * @param endTime hora de finalización

     * @returnLa cadena de diferencia en días

     */

    cadena estática pública calcularDateDifference (DateTime startTime, DateTime endTime, formato de cadena) {

        Días días = Days.daysBetween(startTime, endTime); // Usa Joda-Time para calcular el número de días de diferencia

        diferencia int = días.getDays();

        Resultado de cadena;

        cambiar (formato) {

            caso " día":

                resultado = diferencia + "天";

                romper;

            caso " cuando":

                resultado = diferencia * 24 + " hora";

                romper;

            caso " punto":

                resultado = diferencia * 24 * 60 + " minuto";

                romper;

            por defecto:

                throw new IllegalArgumentException("Formato no válido"); // Si el formato es ilegal, lanza una excepción

        }

        resultado de devolución;

    }

}

// ejemplo de función

// Ejemplo de cálculo del número de días de diferencia entre dos fechas

// Parámetros de entrada: startTime, hora de inicio, el tipo es DateTime; endTime, hora de finalización, el tipo es DateTime; formato, carácter de formato, el tipo es String

// Parámetros de salida: resultado, una cadena de días de diferencia

// ejemplo de llamada:

// DateTime startTime = new DateTime(2022, 1, 1, 0, 0); // Crea un objeto de hora de inicio

// DateTime endTime = new DateTime(2022, 1, 5, 0, 0); // Crea un objeto de hora de finalización

// Resultado de cadena = DateUtils.calculateDateDifference(startTime, endTime, "天");

// System.out.println(resultado);

// Resultado de salida: por ejemplo, calcule la diferencia de días entre el 1 de enero de 2022 y el 5 de enero de 2022: 4

// El resultado de salida es: 4 días

No es difícil encontrar mediante análisis:

1. Anotación : Hay una anotación XML encima del código, que indica que esta clase requiere la versión 2.10.10 de la biblioteca joda-time. Esto es muy importante para comprender las dependencias del código y el entorno de ejecución.

2. Legibilidad : La denominación del nombre de la función es clara y descriptiva, lo que indica la función principal de la función. Los nombres de los parámetros también son claros, lo que facilita la comprensión de qué hace cada parámetro. Cada bloque de código (como declaraciones de importación y cuerpos de funciones) utiliza sangría y espacios en blanco adecuados para que el código sea fácil de leer.

3. Calidad del código :

Es una buena práctica utilizar el método Days.daysBetween para calcular la diferencia en días entre dos fechas porque evita los problemas que pueden surgir al realizar cálculos de diferencia horaria directamente (como el horario de verano, zonas horarias, etc. ) .
La estructura de caja de cambio se utiliza para procesar solicitudes en diferentes formatos, lo que puede satisfacer de manera flexible diferentes necesidades. Para una entrada de formato no válido, el método genera una IllegalArgumentException , que indica el manejo de la excepción.
Se utilizan nombres de variables y nombres de métodos razonables para que el código sea fácil de entender y mantener.
Se utilizan comentarios razonables para explicar la función del código y el papel de los parámetros.
No se utilizan números mágicos ni valores codificados en el código, sino que se utilizan constantes o variables apropiadas.
El tipo de parámetro de entrada es DateTime , lo que hace que la función sea muy versátil y puede aceptar varios formatos de hora.
El tipo de retorno es String , lo que hace que la salida de la función sea buena legible y visualizable.

Si también desea experimentar la experiencia de desarrollo eficiente y de alta calidad que ofrece FuncGPT, descárguela y úsela de forma gratuita: https://c.suo.nz/74QvS

Liberar la productividad del desarrollador: ¿Aprender sobre el código “a nivel de documento”?

Supongo que te gusta