¿Forzar a las personas a leer y entender el código en lugar de usar comentarios, resúmenes de funciones y depuradores? [duplicar]

48

Soy un joven programador (terminé la universidad de ciencias de la computación pero todavía tengo menos de un año de trabajo en la industria) y hace poco conseguí un trabajo trabajando en un código C para un servicio web de tamaño decente. Mirando el código, los únicos lugares donde vi comentarios eran cuando las personas escondían su código anterior. La función y los nombres de variables son similarmente informativos la mayor parte del tiempo - futex_up(&ws->g->conv_lock[conv->id%SPIN]); . Enfrentando a un programador senior sobre la situación y explicando que agregar comentarios y nombres significativos haría que el código sea más fácil de mantener y leer en el futuro, recibí esta respuesta:

  

En general, odio los comentarios. La mayoría de ellos tiempo, como el caso usted.   Mencionar con el valor de retorno, la gente usa comentarios para moverse.   leyendo el codigo Los comentarios no dicen nada más que lo que el   El chico pensó que el código lo hizo en el momento en que hizo el comentario (que es   a menudo antes de su última edición). Si pones comentarios, la gente no lo hará.   Lee el código tanto. Entonces los insectos no son atrapados, y la gente no   comprender las peculiaridades, cuellos de botella, etc. del sistema. Eso es   siempre que los comentarios se actualicen realmente con cambios de código, que es   por supuesto totalmente sin garantía.

     

Quiero forzar a la gente a leer el código. Odio a los depuradores por un   razón similar Son demasiado convenientes y te permiten pasar   código sucio con relojes y puntos de interrupción y encontrar el llamado   problema, cuando el verdadero problema era que hay errores en el código   porque el código no se ha simplificado lo suficiente. Si no tuviéramos el   Depurador, nos negaríamos a leer el código feo y decimos: Tengo que limpiar   esto solo para que pueda ver lo que está haciendo. Para cuando hayas terminado   limpiando, la mitad del tiempo el error desaparece.

Aunque lo que él escribió va mucho en contra de que me hayan enseñado en la universidad, tiene sentido. Sin embargo, dado que la experiencia en los estudios a veces no funciona en la vida real, me gustaría obtener una opinión de las personas más examinadas en el código.

Es el enfoque de evitar comentar el código para hacer que las personas realmente lean el código y entiendan lo que está pasando tiene sentido en un entorno de codificación de tamaño mediano (uno que pueda ser leído en su totalidad por cada persona que trabaje en él dentro de un mes o dos), o es una receta para un desastre a largo plazo? ¿Cuáles son las ventajas y desventajas del enfoque?

    
pregunta ThePiachu 15.06.2013 - 23:33

19 respuestas

97

El código bien escrito debe ser lo suficientemente autodocumentado para que no necesite ningún comentario que explique lo que hace el código, porque es obvio al leer el código en sí. Esto implica también que todas las funciones y variables tienen nombres descriptivos, aunque podría ser necesario para aprender la jerga del problema y los dominios de solución.

Esto no significa que el código bien escrito deba estar completamente sin comentarios, porque los comentarios importantes son aquellos que explican por qué se implementa una función / bloque / etc particular, no trivial, tal como está y por qué no se ha elegido una solución diferente.

El problema con los comentarios que describen el código en sí es que tienden a estar desactualizados, porque el código se modifica para corregir un error, pero los comentarios permanecen intactos. Este es mucho menos el caso de los comentarios que describen el razonamiento para llegar a la solución actual.

    
respondido por el Bart van Ingen Schenau 15.06.2013 - 17:40
53

Alguien (atribuido a Richard C. Haven , un programador de Delphi) escribió una vez:

  • Los principiantes no comentan nada.

  • Los hombres del viaje comentan lo obvio.

    myVar = myVar + 1; // add one to myVar
    
    /* This method adjusts the page margin by the appropriate device offset */
    
  • Los Maestros comentan la razón para no hacerlo de otra manera

    /*
    
    I already tried obvious approaches A, B, and C to solve this problem.
    They didn't work for the following reasons: ...
    
    Therefore I wrote this less-than-obvious approach which works and 
    passes all unit tests.  
    
    */
    

Su "programador sénior" puede ser senior en términos de edad / longevidad, pero a mí me parece que tiene algo de profesional para crecer.

En cuanto a la depuración, hay mucho que decir sobre el código limpio y el uso liberal del registro y / o las declaraciones print() . Sin embargo, al usar un buen depurador, generalmente puedo encontrar el problema en una pequeña fracción del tiempo que llevaría sin él. Es una herramienta de poder. Úsalo.

    
respondido por el Dan Pichelman 20.02.2014 - 01:00
22
  

Quiero forzar a la gente a leer el código. Odio a los depuradores por un   razón similar Son demasiado convenientes y te permiten pasar   código sucio con relojes y puntos de interrupción y encontrar el llamado   problema, cuando el verdadero problema era que hay errores en el código   porque el código no se ha simplificado lo suficiente.

Su programador senior parece tener un problema comprensible sobre el estilo de codificación . Sin embargo, está equivocado en cómo aborda el problema.

Los comentarios

Ambos y la codificación descriptiva son esenciales: un código bien escrito con nombres descriptivos rápidamente le indica qué hace el código ; pero los comentarios le dicen lo que debe hacer el código (y por qué no, por qué lo hace de una manera y no otra . Luego tiene pruebas de unidad para verificar que el "contrato "(lo que el código debería haber hecho ) se cumple, y hágalo de manera automática, frecuente y sin ningún esfuerzo adicional por su parte.

Sin los comentarios, llevaría mucho tiempo (o una prueba de unidad, que en este punto sospecho que a su jefe le gustan incluso menos los comentarios, si cree que los errores pueden ser atrapados por personas que leen el código ) antes de encontrar el error:

// Multiply margin by a fixed amount.
page->margin += fixedMargin;

y, sí, el comentario podría estar equivocado, pero ahora sabes que en una de esas dos líneas hay un error . Esto, además de otro recurso útil, control de versión , le permite encontrar la discrepancia en menos de 30 segundos. Verificación de la salida e incluso el paso con un depurador podría no (por ejemplo, un valor de FixMargin de alrededor de 1.01 podría darle resultados ambiguos).

Si su mentor busca la simplicidad (estoy de acuerdo con él en que es un rasgo deseable), debería implementar alguna forma de verificar métricas como Complejidad ciclomática y establecimiento de objetivos métricos. Eso también se aplica a los comentarios: estoy de acuerdo en que no tiene sentido documentar cada línea de código, pero debe esforzarse por cubrir módulos, funciones y cualquier "punto WTF" en el código.

// Useless comment: multiply a by four

// Useful comment (even if maybe it shouldn't be in this exact point of code):
// Zooming 2:1, four pixels get mapped into one, divisor needs multiplying by four
a *= 4;

Su método puede dar resultados: en caso de que odie, tendrías un 20% de codificación y un 80% de documentación y pruebas. Con su método, obtienes 20% de codificación y 80% de depuración y rascado.

La diferencia entre los dos casos está, creo, en la moral y en la productividad general de las personas. Si documenta y simula las funciones y los módulos de manera adecuada, un que no necesite conocer la imagen global puede implementar un módulo, no tiene que estudiar los efectos secundarios en un escenario de caja negra, y para En conclusión, puede tener menos experiencia .

Al parecer, su mentor se siente cómodo acumulando una cantidad temible de deuda técnica . Revisaría sus estadísticas sobre el deslizamiento de fechas límite y / o ETAs; a menos que sea un milagro, cualquier proyecto de larga duración que no sea mantenido por una banda de un solo hombre o un grupo muy unido de amigos de codificación tendrá su deuda técnica tarde o temprano.

    
respondido por el lserni 20.02.2014 - 00:51
14

Si solo puede "leer el código", no tendrá una idea de lo que la función pretende hacer . Entonces, si alguien lo jode (sé que nadie lo hace, este es un caso hipotético) y hace algo mal, no tiene forma de verificarlo en el código. Tienes que esperar a que las pruebas unitarias lo detecten (si lo comprueban).

Agregue a eso, que no agregar comentarios me obliga a leer las funciones A1, A2, A3 ... de principio a fin, mientras que solo me interesa entender la función A, que llama a todo lo anterior.

Apostaría a que tu programador senior sea perezoso (malo) o que la gente se dé cuenta de lo hábilmente que él codifica (mucho peor).

    
respondido por el SJuan76 20.02.2014 - 00:49
8
  

Si pones comentarios, la gente no leerá el código tanto. Entonces los errores no son atrapados, y la gente no entiende las peculiaridades, cuellos de botella, etc. del sistema. Esto se proporciona siempre que los comentarios se actualicen con cambios de código, lo que, por supuesto, no está totalmente garantizado.

Nada como un idiota de opinión.

La próxima vez que esté comprando un libro para leer. Asegúrese de leerlo de principio a fin antes de comprarlo. De lo contrario, nunca sabrá exactamente si es lo que estaba buscando comprar. Eso es básicamente lo que te está diciendo que hagas.

Él ha hecho algunas suposiciones que son tontas.

  1. Leer el código fuente te proporcionará la perspectiva purista de lo que hace.
  2. Los comentarios se refieren al scope del código fuente al que están asociados.

Esa es su estrecha perspectiva sobre los comentarios, y como tal no ve ningún valor en ellos. Aquí están las limitaciones de no tener comentarios.

  1. El código fuente es un conjunto de instrucciones para una computadora. No expresa conceptos o ideas. Por lo tanto, el código fuente nunca te dirá cuáles fueron los objetivos de los programadores. El código fuente que se compila sin errores y no se bloquea puede fallar en el cumplimiento de los objetivos. ¿Cómo sabrás algo diferente de la computadora leyendo el código fuente? La computadora ya lo hace, pero aún así podría no cumplir con el objetivo.
  2. El código fuente no explica la intención del programador. open window, prompt for deposit no explica que el programador intentara comunicar una advertencia al usuario.

La próxima vez que tenga una conversación con este tipo, él le preguntará por qué agrega comentarios a su código fuente. Responde con esta declaración.

  

"Escribo el código fuente para decirle a la computadora qué hacer, y escribo comentarios para decirle a la gente qué hacer".

    
respondido por el cgTag 15.06.2013 - 23:53
6

Los comentarios deben usarse como un registro escrito que explique algo confuso. Si está escribiendo algo que es potencialmente confuso y no se puede simplificar, por lo que sospecha que incluso le costará entenderlo seis meses después, escriba un comentario.

Si comenta generosamente, todo y en todas partes, entonces los comentarios pierden su eficacia para señalar las dificultades. (Recuerda la fábula del niño que gritó "¡Lobo!")

Los comentarios ocupan "pantalla de bienes raíces", a menos que tenga un buen editor de plegado; Tienes que seguir saltándolos cuando te mueves en el código. Y, por supuesto, los comentarios como /* increment i by one */ junto a i++ son basura completa.

Si el código es tan complicado que requiere una guía para las partes internas, entonces, por supuesto, escriba una guía para las partes internas. Llámelo README-internals.txt (o quizás HTML) y guárdelo en el mismo directorio que el código, e ingrese un comentario que diga /* this is all explained in README-internals.txt */ .

Acerca de los depuradores: cualquier herramienta que le ayude a encontrar un error es valiosa. Es tonto despedir herramientas. Los depuradores de punto de interrupción no deben usarse para verificar que el código está funcionando. Al menos, no se confía en como medio primario. Un depurador pasará alegremente una declaración como a[i] = i++ en C y confirmará una mala intuición.

Sin embargo, se puede confiar en las herramientas de depuración que realmente detectan algún tipo de violación en tiempo de ejecución como una herramienta de prueba. Si tiene un depurador que detecta el uso indebido de la memoria dinámica y el código pasa numerosos casos de prueba bajo ese depurador, es una fuente de confianza de que la memoria no se está utilizando incorrectamente.

Entonces, tenga en cuenta que "depurador" se refiere a más de un tipo de herramienta, no solo a un depurador de punto de interrupción / paso. Algunos depuradores solo proporcionan una vista del programa, lo que le permite razonar sobre lo que está mal, mientras que otros depuradores le buscan problemas.

El código no siempre se puede simplificar por no tener un depurador o negarse a usar uno. ¿Qué sucede si sigue la sugerencia de su jefe y simplifica el código hasta el punto de que ya no se puede simplificar más y aún necesita un depurador?

    
respondido por el Kaz 15.06.2013 - 20:22
5

Me parece que la revisión del código es un proceso fantástico para responder a esta pregunta de manera concreta. Si leo la solicitud de atracción de alguien (haciendo un esfuerzo real por leerlo, no solo mirándolo con la actitud de que todo debe ser evidente de inmediato) y no puedo entender lo que hace, le digo a la gente que agregue un comentario. O puedes hacerlo solo con un pato de goma.

La mayoría de las personas saben de manera inofensiva qué ideas deben comentarse: es lo que le dirías a alguien que esté a tu lado si te hicieran una pregunta sobre el código. A menudo le pediré a alguien que explique algo en una revisión, dará una gran respuesta y mi respuesta es "Copie la explicación que acaba de escribir en un comentario en el código".

Pero por alguna razón, rara vez es el contenido que las personas terminan escribiendo en sus comentarios. En lugar de eso, la gente escribe cosas inane como

/**
 * Gets the {@link List} of {@link Author}s for the given {@link Book}.
 *
 * @param book The {@link Book} for which you want the {@link Author}s.
 * @return All of the {@link Author}s for the given {@link Book}.
 */
List<Author> getAuthors(Book book) { ...

y

// increment i by 1
i += 1

y ese es el tipo de cosas a las que los compañeros de trabajo experimentados están reaccionando. Yo mismo les digo a las personas cuando estoy revisando el código para eliminar este tipo de comentarios de bajo nivel que no agregan más información de la que se puede encontrar en las líneas que lo rodean inmediatamente.

Un ejemplo principal de una cosa trivial que necesita necesita ser comentada es la descripción de los tipos de pato en lenguajes dinámicos. Si el argumento o el valor de retorno de una función es un dictado con un montón de propiedades en él, más adelante te encontrarás con una locura si no comentas exactamente cuáles son esas propiedades.

Ninguna cantidad de comentarios elevará ningún código no trivial al nivel que un niño de 8 años pueda entender, por lo que no debe intentarlo. Debe hacer algunas suposiciones de que el lector sabe cómo leer el código, porque de lo contrario es un esfuerzo completamente inútil.

Finalmente, los comentarios son muy a menudo incorrectos. La gente a menudo los omite cuando lee, y no los actualiza cuando las cosas cambian. No puede escribir una prueba de unidad para sus comentarios, por lo que solo la forma de defender su código contra la podredumbre que se produce cuando sus compañeros de trabajo descuidados comienzan a hacer burla es comentar que solo las ideas son esenciales. Los comentarios que no agregan valor agregan valor negativo cuando se vuelven erróneos.

Diseño de documentos, ideas, arquitectura, historia, razón de ser, no líneas de código.

    
respondido por el Christopher Martin 16.06.2013 - 00:19
4

En un mundo perfecto sin plazos, su enfoque podría funcionar.

  

Un usuario informó un error en la aplicación X. Dejaremos que el nuevo usuario pase dos meses para obtener una comprensión profunda y exhaustiva del código, y luego tal vez agregar algunas semanas de refactorización. Si el error persiste, debería poder encontrarlo en ese momento y ni siquiera necesitará un depurador.

En el mundo real, esto suena como una forma confiable de salir del negocio.

    
respondido por el Heinzi 15.06.2013 - 22:10
4

Ejemplo de mal comentario

foo(); //calling function foo

Buen comentario

foo(); // must call function foo, because of a bug {link to bug}
    
respondido por el Lukasz Madon 16.06.2013 - 02:41
3

Code Complete, el trabajo seminal sobre el estilo de codificación dedica varias secciones (comenzando con 19.3 en la edición 1) a la pregunta de los comentarios: lo bueno, lo malo y lo feo. Por lo tanto, usted y su desarrollador senior, probablemente deberían echar un vistazo allí.

Habiendo dicho eso, los comentarios bien escritos y bien colocados son muy importantes en la OMI, para cualquier proyecto a gran escala / a largo plazo.

En un mundo perfecto, es cierto que los comentarios no serían importantes . Pero a menos que tenga una memoria fotográfica y todos los que trabajan en su código son genios, los buenos comentarios solo ayudan a entender el código mucho más rápido cuando tiene que volver a él uno o dos años más tarde y modificarlo, o alguien más lo hereda. tu codigo. (Lo digo, después de haber trabajado profesionalmente durante 20 años y de 5 o 7 años en un proyecto con otros desarrolladores involucrados)

Hace unos años heredé una aplicación compleja que hace el trabajo pero que tiene una arquitectura deficiente y un estilo de codificación inconsistente e inflado. Afortunadamente, el código está bastante bien comentado, lo que me ahorró días y semanas para ponerme al día con ese código base.

Otra cosa que me ayudó a ponerme al día fue el depurador que uso. Cuando voy a analizar una nueva pieza de software en la que tengo que trabajar, una de las primeras cosas que hago es revisar todos los menús, hacer selecciones no válidas o extrañas y ver si puedo interrumpir la aplicación. Cuando lo rompo, ejecuto ese escenario con el depurador y veo a dónde me lleva esa falla. Casi invariablemente, esto me lleva a módulos y coyunturas importantes en el código base: una forma rápida de encontrar los lugares importantes en el mapa.

Aunque con mi propio código generalmente no tengo que usar mucho el depurador, hay ocasiones en las que ayuda, nadie es perfecto, incluso si son meticulosos con las pruebas de unidad (lo que a menudo es imposible cuando código heredado estrechamente acoplado.) Y si uso un nuevo módulo o componente, el depurador me ayuda a encontrar rápidamente los errores y malentendidos con los que tengo que lidiar para ayudarme a actualizar las nuevas cosas.

En resumen: el tiempo es dinero, y la mayoría de nosotros programamos entregar productos y pagar las cuentas . Pasar semanas y horas revisando cientos de líneas de código para encontrar un error que el depurador revelaría en 10 segundos, o un código mal escrito que podría estar iluminado por algunos buenos comentarios, no ayudará mucho a su línea de fondo ...

Su desarrollador senior aparentemente no se preocupa por la eficiencia y preferiría que los desarrolladores pasen horas y días jugando con código complejo, cuando unos pocos comentarios salvarían el día. Lo mismo ocurre con sus ideas sobre la depuración. (Solo curiosidad: ¿el desarrollador senior utiliza un IDE? ¿Por qué no escribe todo en un archivo de texto y hace una compilación y un enlace desde la línea de comandos, etc.? ¿Qué mejor manera de entender cada línea de código ...)

    
respondido por el Mikey 16.06.2013 - 23:08
2
  

Los comentarios no dicen nada más que lo que el chico pensó   El código lo hace en el momento en que lo puso en el comentario

Ya sabes, es un enfoque extremadamente teórico. No me sorprendería, si lo dijera un matemático teórico, pero en los sonidos de un desarrollador senior no suena como si fuera alguien con una práctica muy larga.

Bueno, en teoría, puedes analizar el código en la cabeza, pero funciona solo con programas muy simples. Con los más complejos, de la vida real, te encuentras con el Detener el problema , que es uno de los problemas más complejos de la teoría de la computación. Si alguien dice que puede analizar programas en la cabeza, probablemente pueda hacer el desencriptado RSA en la memoria :)

Parece que su desarrollador senior no tiene experiencia en la vida real con problemas complejos, o está tratando de impresionarlo con trucos tomados de la película Hackers , o quiere justificar su propia pereza cuando se trata de escribir comentarios.

    
respondido por el Danubian Sailor 16.06.2013 - 03:29
2

Los comentarios son para quién , cuando , por qué , suposiciones , dependencias , y posiblemente cómo .

¿Quién escribió esto? ¿A quién me dirijo y me molesto si tengo preguntas al respecto?

¿Cuándo lo escribieron?

¿Por qué lo escribieron? ¿Cuál fue la razón comercial por la que pasaron un tiempo escribiendo código?

¿Por qué eligieron este enfoque y qué otros enfoques rechazaron y por qué?

¿Qué suposiciones hicieron? ¿Qué creencias sobre la organización tenían?

¿Qué cosas deben pasar para que este código se ejecute correctamente? ¿De qué bibliotecas, objetos, entornos u otras cosas depende?

¿Cuáles son las situaciones en las que el código puede fallar y cómo el código maneja esas fallas? ¿Cómo trato con ellos?

En cuanto al "cómo", los comentarios solo deben explicar cómo funciona el código si es complicado y difícil de entender (y si es así, tal vez el programador debería haber puesto más esfuerzo en simplificarlo).

    
respondido por el Greenstone Walker 16.06.2013 - 14:03
1

A lo que se refiere su desarrollador senior es a la entropía de códigos. Me imagino que se refiere a casos en los que el código está mal diseñado, y la única manera de entenderlo bien y trabajar con él son los comentarios y el depurador.

En otras palabras, los comentarios y los depuradores se pueden utilizar para solucionar los problemas subyacentes. Sin embargo, ambas son herramientas, y culpar a la herramienta no es una forma efectiva de hacer nada.

Para su ejemplo, si una base de código tiene una gran cantidad de códigos rotos, entonces la solución es no dejar de lado los comentarios y hacer que todos lean todo el código que sea posible. De hecho, esto es una pérdida de tiempo y recursos. En su lugar, configure procesos como la revisión por pares y la programación en pares, donde el código escrito por una persona seguramente será revisado por otra. Estos procesos no solo logran el mismo objetivo con mayor precisión, sino que también evitan el desperdicio de recursos donde docenas de desarrolladores tienen que entender un fragmento de código complejo, simplemente porque carece de comentarios y documentación.

Además, los comentarios eficientes pueden reducir la cantidad de error en el código. Leerlos hace que el código fuente sea más fácil de entender y, a menudo, le evita tener que buscar en lotes enteros de archivos fuente, solo para descubrir por qué es necesaria una línea de código. Claro, el comentario puede resultar incorrecto. Pero a menos que la calidad general del proyecto sea absolutamente horrible, terminará ahorrando más tiempo confiando en los comentarios precisos, de lo que perderá ante aquellos que están desactualizados. Y el ahorro de tiempo en la comprensión significa más tiempo para refactorizar, que es una forma mucho mejor de combatir la entropía de códigos.

    
respondido por el cib 15.06.2013 - 23:48
1

Estoy escribiendo el código durante aproximadamente 30 años y es posible que haya dicho algo muy similar a lo que dijo ese programador senior. También estoy muy consciente de los problemas de mantenimiento.

Aún creo que algunos puntos muy importantes se olvidaron en las respuestas anteriores:

Tengo pruebas unitarias para la mayor parte de mi código. ¿No?

El por qué de las funciones (la intención detrás del código) generalmente se expresa a través de pruebas y si las pruebas por sí mismas no son suficientes, se comentan, a veces muy intensamente (si alguno de ustedes escuchó sobre programación de litterate pueden entender de lo que estoy hablando).

En los comentarios opuestos en mi código son muy escasos, casi inexistentes, excepto en dos casos especiales: - si se implementa si se siguen algunas referencias normativas (como implementaciones de protocolos de red, en qué estoy trabajando actualmente), generalmente pongo la referencia como comentario sobre el código. - También uso comentarios para evitar interrumpir el flujo de programación. Inserto comentarios como: esto o aquello se ven mal, corríjalo más tarde cuando esté codificando alguna función no relacionada. Estos son comentarios a corto plazo (como las advertencias definidas por el programador) y deben corregirse más adelante.

Mi razonamiento al hacer eso es que los comentarios en el código pueden ser engañosos. Puede leer fácilmente un comentario y creer que el código está realizando lo que pretende el comentario, incluso si no es cierto.

Cuando los comentarios sobre el código están en las pruebas, las cosas son diferentes. Explica cómo se debe llamar al código y la prueba garantiza que realmente esté haciendo eso.

Normalmente no uso mucho a los depuradores. Los guardo para algunos casos especiales (sobre todo cuando no entiendo lo que hace el código, como errores de hardware extraños).

Eso cambió con el tiempo. Hace 30 años utilicé mucho a los depuradores. Lo que he observado es que encontrar errores suele ser mucho más lento que otros métodos. Lo que normalmente hago ahora es detectar errores en pruebas unitarias, cuanto antes mejor. Eso tiene la ventaja adicional de dar una prueba de no regresión. Nunca mordido dos veces por el mismo error.

    
respondido por el kriss 16.06.2013 - 05:02
1

Solía comentar mucho, ahora muy poco, hacer que el código y los nombres de las variables sean legibles es el camino a seguir.
Agrego comentarios para 'errores' reales y 'por qué esto no se hizo (aún) no es obvio en el código'.

Pero a tu pregunta REAL.

Observo que tu título comienza con la palabra: "forzar"

También observo que el primer párrafo menciona "confrontar"

Utilicé exactamente las mismas palabras hace 20 años yo mismo

Esto (IMHO, por supuesto) es de lo que realmente se trata la programación: cómo pueden trabajar juntas diferentes personas con diferentes estilos, opiniones, experiencias, conocimientos y antecedentes.

No hay una solución simple, no hay una lista de pasos programáticos a seguir, ni una sola conversación para arreglar las cosas. Le recomendaría que reflexione sobre los siguientes puntos que he aprendido de mi experiencia de 20 años.

  1. escucha
  2. escucha
  3. escucha. Lamento haberlo hecho tan importante, pero nada lo ayudará más en su carrera ahora que hacer preguntas y escuchar incluso si la respuesta no tiene sentido.
  4. Haga preguntas y solo escuche las respuestas, incluso si no está de acuerdo o no las entiende completamente. Casi siempre hay una segunda oportunidad para revisar las cosas.
  5. Acepta que las cosas se sacan a veces. Si son decisiones realmente malas, se seguirán mostrando y luego se puede presentar un caso para mejorarlas. Pero el énfasis en el posterior. Lo suficientemente bueno por ahora es algo que debes aceptar algunas veces para que puedas más por ahora.
  6. Elige tus batallas sobre las cosas que están mal. Aprenda a no hablar con la lengua a menos que el elemento sea realmente importante para usted e incluso luego elija sus batallas con mucho cuidado, ¡e intente entablar conversaciones y no batallas!
  7. Acepta las diferencias. Fuera de la academia, tendrá que aceptar más diferencias y concentrarse un poco (menos) en encontrar la forma "correcta y verdadera" de hacer las cosas y más en lo que funciona hoy y para el negocio en el que trabaja.
  8. Evita conversaciones en blanco y negro. No sea absoluto acerca de lo "correcto", evite las palabras que son absolutistas como "debe", "solo", "imposible", etc., y use palabras como "debería" "a menudo" y "difícil".
  9. Use ejemplos concretos en la conversación en lugar de la teoría. No evite la teoría, pero en las conversaciones trate de tener ejemplos reales para sus puntos. Si no tiene ejemplos del mundo real, este puede ser un indicador de que debería enumerar más que hablar.
  10. Enfatiza tu juventud e ignorancia en conversaciones con programadores más experimentados, como el que mencionas. Los impresionará más con humildad que con su conocimiento adquirido recientemente.
respondido por el Michael Durrant 17.06.2013 - 22:44
0

Los comentarios están muy sobrevalorados y se utilizan con mayor frecuencia. Aunque no conozco su situación actual (ya que no encuentro la cita citada que indique la buena legibilidad del código), en general no debería distribuir los comentarios en todo el código (quizás con la excepción de los comentarios de alto nivel, que son ya cerca de la documentación0.

Es por una razón que comentar es uno de los olores de código descritos en el libro de refactorización de Martin Fowlers (para obtener un resumen, consulte: enlace , el libro no está disponible gratuitamente en este sitio).

Sin embargo, deberías sustituir los comentarios con nombres significativos de métodos y variables, y no creo que clasifiquen w y gs . Sin embargo, personalmente, presionaría más sobre una buena denominación que sobre comentar.

Por cierto, si busca 'código limpio' y 'comentarios' o 'olor de código' y 'comentarios' encontrará excelentes lecturas sobre esto, es decir. enlace (con un resumen de por qué el tío Bob Martin de Clean Code no está de acuerdo con los comentarios)

    
respondido por el markijbema 15.06.2013 - 22:34
0

Cada vez que escriba un código, debe pensar en el próximo programador que heredará lo que escribió. Si escribes comentarios porque te enseñaron a hacerlo como una mejor práctica o simplemente por costumbre, probablemente deberías dejar de escribir comentarios todo el tiempo porque cualquiera que lea tus cosas comenzará a ignorarlos como inútiles.

Si solo comentas cuando nombras convenciones y estructuras no puedes explicar algún elemento extraño de lo que estás haciendo (generalmente debido a algo más en una base de código que es completamente una mierda), se darán cuenta de eso. Si está marcando bits de código problemáticos, por gritar en voz alta ponga una fecha en él para que sea más fácil revisar los cambios que llevaron a los chanchullos en el control de la fuente.

Sobre el tema de los depuradores, puedo sentir una punzada de solidaridad en el tipo de procedimiento de la vieja escuela (supongo), porque procedo de JavaScript que comienza cuando todos los IE dijeron que era "Objeto no encontrado". Por qué incluso se molestaron, no lo sé, pero cuando ocasionalmente tienes que lidiar con ese tipo de cosas, piensas mucho más en cómo estructurar tu código de tal manera que va a ser mucho más obvio dónde se fue algo. mal, así que puedes diagnosticar rápidamente con el registro / alertas.

Dicho esto, no cambiaría las herramientas Chrome Dev o Firebug por nada menos que una caja policial que viaja en el tiempo. Pero el punto, creo, es este. Si lo primero que debe hacer es iniciar un rastreo en el depurador sin siquiera mirar el código involucrado, es posible que no esté estructurando su código tan bien como podría. Siempre trate de ser tan directo, obvio, minimalista y fácil de leer como si no hubiera un IDE o un depurador para ayudarlo. Comience por mirar su código cuando tenga un problema. Si no es fácil adivinar dónde van las cosas mal, es posible que desee pensar un poco más en cómo escribiría el código sin las herramientas modernas. La mayoría de las aplicaciones Java y C # que he visto no tienen ni idea de los fundamentos básicos de la POO.

    
respondido por el Erik Reppen 16.06.2013 - 00:33
0

Los comentarios en el código son una bendición cuando se usan correctamente, pero como otros aquí han señalado, a menudo se usan en exceso. No voy a repetir lo que ya se ha señalado, pero diré que solo debes comentar si sabes que el código que estás escribiendo es complicado y no hay otra forma viable.

Si siente que tiene que comentar, piense primero en el código y pregúntese; ¿Por qué estás escribiendo ese comentario? ¿Hay otra forma de escribir el código que no necesite un comentario?

No escriba comentarios por el simple hecho de escribir comentarios. Comente solo como último recurso o donde ayudará a aquellos que van a tener que trabajar en el código más adelante. Si te encuentras escribiendo comentarios que describen lo que está haciendo una variable, es probable que estés sobre-comentando. Los malos programadores comentan todo, los buenos programadores solo comentan cuando es necesario.

Sobre el tema de los depuradores, trabajo con algunos ingenieros que han hecho toda su carrera sin haber iniciado nunca un depurador. ¿Por qué? Un depurador es una herramienta como cualquier otra. Al igual que en la mayoría de los casos, un martillo de bola hará el trabajo, a veces necesitas algo con más delicadeza.

Un depurador sirve dos propósitos.

  1. Se usa para encontrar errores
  2. Muestra una ruta a través de tu código.

Pueden ser muy útiles para poner al día a los recién llegados y pueden ser incluso más útiles para rastrear aquellos errores muy difíciles de encontrar, pero no son la única manera y hay ocasiones en que un depurador es en realidad un obstáculo más que un obstáculo. ayuda.

En cuanto al resumen de funciones, todas las funciones deben tener un bloque de documentos, esto es imprescindible, pero no hagas que sean largos y elaborados. El resumen debe ser una descripción de 1 línea con cada parámetro que se describe claramente.

/**
 * A getter method for foo
 *
 * @param bool $bar If true, bar will be attached to foo
 *
 * @return foo
 */

Utilice solo un docblock detallado si hay una causa. Si el método es demasiado complicado, entonces sí, ponga una explicación pero, cuando sea posible, intente evitarlo. Un buen código debería documentarse a sí mismo.

Recuerde, todos disfrutan leyendo novelas, pero nadie quiere leer guerra y paz a las 9 am el lunes por la mañana.

    
respondido por el mplf 16.06.2013 - 04:10
-1

Los comentarios son muy útiles y pueden ser la diferencia entre el código claro y el código no claro.

El hecho de que se haya hecho de una manera "en el pasado" no significa que otra manera sea inaceptable.

    
respondido por el CaptainXD 16.06.2013 - 01:51

Lea otras preguntas en las etiquetas