Las palabras "código autodocumentado" es otra forma de decir "código legible". Por sí solo, no reemplazará esta documentación o buenos comentarios , pero con o sin ellos definitivamente hará que su vida y la de sus colegas sean más fáciles.
Veamos algunos principios importantes para crear código autodocumentado.
No use "números mágicos"
Dime, ¿qué significa esta línea?
if (students.length > 23) {
Comprueba si hay más estudiantes que 23? ¿Y qué significa eso? ¿Por qué exactamente 23, y no, digamos, 24?
Un número mágico es un número sin contexto. Deberá dedicar tiempo y esfuerzo para comprender este contexto. Deshágase del trabajo innecesario, de inmediato explícitamente asigne al número la designación:
const maxClassSize = 23; if (students.length > maxClassSize) {
Intenta leer el código ahora. No verificamos "si hay más estudiantes que 23", sino "si hay más estudiantes de los que acomoda la clase".
Use nombres claros para las variables
No sé por qué, pero antes tenía miedo constantemente de hacer largos los nombres de las variables. Lo cual fue estúpido de mi parte, ya que rStuNms y fStuNms son terribles en comparación con r awStudentNames y filterStudentNames .
¿El último todavía parece ser largo? Luego piense en esto: después de 2 semanas de vacaciones y trabajando con otro código, olvidará una buena mitad de las abreviaturas. A saber, la capacidad de leer nombres de variables sobre la marcha es la capacidad de leer código sobre la marcha:
const fStuNms = stus.map(s => sn)
Otro buen consejo es usar convenciones (convenciones de nomenclatura). Si la variable es booleana, comience su nombre con is o has ( isEnrolled: true ). Si la variable es una matriz, use el plural ( estudiantes ). Muchos números deben comenzar con min o max . Y los nombres de funciones deben contener un verbo, por ejemplo, createSchedule o updateNickname . Hablando de características ...
Escribe pequeñas funciones con nombre
Las variables no son la única forma de leer el código. Como joven programador, usaba funciones solo para evitar la duplicación de código . La verdadera revelación para mí fue que, antes que nada, tiene sentido crear funciones para describir lo que está sucediendo .
Tómese un par de segundos para mirar este código y decir lo que hace:
const handleSubmit = (event) => { event.preventDefault(); NoteAdapter.update(currentNote) .then(() => { setCurrentAlert('Saved!') setIsAlertVisible(true); setTimeout(() => setIsAlertVisible(false), 2000); }) .then(() => { if (hasTitleChanged) { context.setRefreshTitles(true); setHasTitleChanged(false); } }); };
Ahora haga lo mismo para el código:
const showSaveAlertFor = (milliseconds) => () => { setCurrentAlert('Saved!') setIsAlertVisible(true); setTimeout( () => setIsAlertVisible(false), milliseconds, ); }; const updateTitleIfNew = () => { if (hasTitleChanged) { context.setRefreshTitles(true); setHasTitleChanged(false); } }; const handleSubmit = (event) => { event.preventDefault(); NoteAdapter.update(currentNote) .then(showSaveAlertFor(2000)) .then(updateTitleIfNew); };
Parece que hay más personajes, pero ¿cuánto más legible, verdad? Todo lo que se necesitaba era distribuir las operaciones lógicas en pequeñas funciones con nombre. Además, las pequeñas funciones en sí mismas no son necesarias para leer en la mayoría de las situaciones; estos son detalles de implementación. Para comprender el código, solo mire la función superior, que consiste en una cadena de eventos fáciles de entender.
Pero además, más aún, un poco más tarde se dará cuenta de que estas funciones pequeñas son muy fáciles de reutilizar. La reutilización es una consecuencia de la legibilidad mejorada, y no al revés.
Agregue descripciones de prueba útiles
Probablemente lo menos comentado son las pruebas auto documentadas, pero en vano.
Digamos que tenemos una función como esta:
const getDailySchedule = (student, dayOfWeek) => {
Imagine que contiene muchas operaciones diferentes: recibe un horario para un mes; si hoy es un día libre, devuelve una matriz vacía; si el alumno está matriculado en clases adicionales, las agrega al final del día, etc. En general, entendió la idea: la función es compleja y sería bueno escribir el algoritmo de su trabajo en algún lugar con palabras simples.
Intentar encajarlo en un comentario es una mala idea: un comentario una vez se volverá obsoleto y no el hecho de que se corregirá a tiempo. ¿Sabes dónde es apropiada la grabación del algoritmo de operación? En pruebas:
describe('getDailySchedule ', () => { it(" ", () => { it(' , ', () => { it(' ', () => {
Esta es la forma más elegante de comentar código sin comentar en el código.
En pocas palabras: la legibilidad es más importante que la inteligencia
Cualquiera puede escribir código que sea comprensible para sí mismo; un buen desarrollador escribe código que es comprensible para otros . Rara vez es algo importante creado por una sola persona, lo que significa que tarde o temprano otras personas leerán su código. Pero incluso si está seguro de que solo leerá un código, considere que hoy y usted, en un mes, son personas diferentes en términos de la capacidad de recordar este código.