¿Cómo lleva un registro de las clases y funciones que ha escrito su equipo?

43

Cuando trabajo en código, enfrento muchos de los mismos desafíos que enfrentan mis compañeros de equipo, y he escrito algunas funciones y clases útiles, y ellos también. Si hay una buena comunicación, escucharé sobre algo genial que alguien armó, y seis meses después, cuando lo necesite, lo recordaré y llamaré a esa función, ahorrándome tiempo. Si no lo recuerdo, o si nunca lo supe, probablemente reinventaré la rueda.

¿Existe una práctica particular de documentar este tipo de cosas? ¿Cómo los haces fáciles de encontrar?

Si su equipo no tiene dicha documentación, ¿cómo puede saber si su rueda ya existe?

EDITAR:

Hasta ahora, todas menos una de las respuestas se ocupan de una situación ideal, así que permítanme resumir esas soluciones: documentación y comunicación; wikis, reuniones de pie, etc. Esas son cosas geniales, pero dependen de que los programadores tengan el tiempo (y las habilidades) para escribir la documentación y asistir a las reuniones y tomar notas y recordar todo.

La respuesta más popular hasta ahora (la de Caleb) es la única que podría ser utilizada por un programador que no es capaz de documentar y reunirse, y que solo hace una cosa: programar. La programación es lo que hace un programador, y sí, un gran programador puede escribir documentación, pruebas unitarias, etc., pero seamos sinceros, la mayoría de nosotros preferimos programar a documentar. Su solución es una en la que el programador reconoce el código reutilizable y lo saca a su propia clase o repositorio o lo que sea, y por el hecho de que está aislado, se vuelve fácil de encontrar y facilita la curva de aprendizaje para usarlo ... . y esto se logró mediante la programación.

En cierto modo, lo veo así: acabo de escribir tres funciones, y se me ocurre que alguien más debería saber sobre ellas. Podría documentarlos, escribirlos, anunciarlos en una reunión, etc., lo que puedo hacer, pero no es mi fortaleza, o ... puedo extraerlos a una clase, nombrarlo bien, hacer que funcionen como un cuadro negro y pegarlo donde van los archivos de otras clases. Luego, un breve correo electrónico anunciando que es fácil. Otros desarrolladores pueden escanear el código y comprenderlo mejor de lo que lo harían con una función aislada utilizada en un código que no entienden completamente: ese contexto se elimina.

Me gusta esto porque significa que tener un conjunto de archivos de clase bien nombrados, con métodos bien nombrados, es una buena solución que se logra mediante una buena programación. No requiere reuniones y suaviza la necesidad de documentación detallada.

¿Hay más ideas en este sentido ... para desarrolladores aislados y con poco tiempo?

changokun
fuente
55
Ampliaría la pregunta para hacerla a mayor escala, tal vez en una empresa de más de 100 empleados, ¿cómo haces lo mismo? ¿Qué mejores prácticas se pueden hacer para evitar la duplicación del trabajo realizado anteriormente?
Asaf
1
@Asaf: sospecho que la respuesta correcta dependerá del tamaño de la población: lo que funciona para una tienda de 5 personas no funcionará para 50, y lo que funciona para 50 no funcionará para 500. Las respuestas a todos serían bienvenidas.
Dan Pichelman
3
¡Esta es una gran pregunta!
Rocklan
44
Ley de Conway : "las organizaciones que diseñan sistemas ... están obligadas a producir diseños que son copias de las estructuras de comunicación de estas organizaciones".
Mark Rushakoff el
2
@nathanhayfield: esa es una solución que puede funcionar para 1 dev, y hasta cierto punto para 2, pero no para 20 o 100. E incluso cuando trabajo solo, prefiero separar temáticamente las funciones auxiliares.
Doc Brown

Respuestas:

29

Bibliotecas Marcos. Control de versiones.

Si tiene código reutilizable, lo último que desea es que diferentes miembros del equipo copien el código fuente en su proyecto. Si lo hacen, lo más probable es que cambien un poco aquí y se ajusten un poco allí, y pronto tendrá docenas de funciones o métodos que tienen el mismo nombre pero que funcionan de manera un poco diferente. O, quizás más probablemente, el autor original continuará refinando el código para corregir errores, hacerlo más eficiente o agregar funciones, pero el código copiado nunca se actualizará. El nombre técnico para eso es un gran desastre .

La solución correcta es sacar esas cosas reutilizables de cualquier proyecto para el que lo construyó en primer lugar y ponerlo en una biblioteca o marco en su propio repositorio de control de versiones. Eso hace que sea fácil de encontrar, pero también desalienta hacer cambios sin tener en cuenta todos los demás proyectos que podrían estar utilizándolo. Puede considerar tener varias bibliotecas diferentes: una para código bien probado que ya no es probable que cambie, otra para cosas que parecen estables pero que no se han probado y revisado a fondo, una para las adiciones propuestas.

Caleb
fuente
55
También me gustaría recomendar tener un conjunto muy completo de pruebas de regresión para la biblioteca reutilizable. Incluso si el cambio parece inofensivo, alguien podría depender de ese comportamiento.
Bobson
2
Pensé que el término técnico era BBOM .
zzzzBov
2
Su respuesta suena razonable a primera vista, y en escala más pequeña a mediana lo es, pero también he visto el lado oscuro de una directiva de "no copiar". Si tiene diferentes equipos para diferentes productos, con diferentes términos de licencia, diferentes ciclos de vida y diferentes contratos de mantenimiento, lo último que desea es acoplar los diferentes productos a una biblioteca casera de fragmentos de código que no cumple con los requisitos de mantenimiento . Las bibliotecas para ese tipo de escenario deben tener una calidad muy alta, y a veces es aún más eficiente que un equipo copie el código y ...
Doc Brown
3
@Caleb: mantén la calma, lee mi publicación por completo. Mi punto es: copiar el código de otra parte, modificarlo e integrarlo en la biblioteca de un equipo no necesariamente lo lleva al "camino de la perdición". Cuando tiene dos bibliotecas con una funcionalidad superpuesta y dos equipos de los cuales cada uno es responsable de mantener su biblioteca, la situación no es tan mala. Eso no es perfecto, ya que un equipo puede hacer algún trabajo que el otro también, pero a veces la ventaja de que esos equipos siguen siendo independientes supera el doble trabajo.
Doc Brown
1
@DocBrown No son situaciones en las que se hace necesario para copiar el código, sino que debe ser una decisión consciente y no algo que se ve obligado a hacer debido a la forma en que el código fue compartido en el primer lugar.
Caleb
13

Un enfoque para eso es configurar un Wiki para ese propósito, y escribir algunos documentos de alto nivel sobre qué componentes reutilizables tiene, cómo resolvió un problema, etc.

La parte difícil es lograr que todos en su equipo mantengan constantemente esa Wiki. Pero cualquier otro tipo de documentación sufre el mismo problema.

Parte de su código también puede ser lo suficientemente bueno como para colocarlo en una biblioteca reutilizable. Esto también hace que sea más fácil encontrar el código nuevamente más tarde.

Doc Brown
fuente
55
Un wiki no es la forma correcta de difundir código. Es una excelente manera de comunicarse sobre el código, pero (vea mi respuesta) no quiere que la gente copie nada más grande que un fragmento de un wiki y lo pegue en su proyecto.
Caleb
@Caleb la comunicación es la parte difícil
jk.
@jk: los problemas de comunicación se agravan si no tiene el control de fuente mencionado en C
JeffO
3
@Caleb: la pregunta del OP no se trataba de difundir el código, sino de comunicarse y encontrarlo más tarde.
Doc Brown
@DocBrown Una vez más, los wikis son excelentes para comunicarse, y probablemente por eso herramientas como GitHub tienen uno incorporado. Pero lo que hace que el código sea fácil de encontrar no es que se mencione en una wiki, es que se mantiene en un lugar conocido. Eso podría ser un wiki, pero si estamos hablando de código que la gente realmente va a usar (frente a un montón de fragmentos que ilustran una solución), debería ser una biblioteca de algún tipo, algo que se pueda construir, probar y que se puede incorporar sin multiplicar el número de lugares donde tarde o temprano necesitará actualizarse.
Caleb
7

Estar en una empresa con 700 empleados, dentro de equipos que varían entre 2 y 20 personas, aquí está mi experiencia.

A nivel de equipo

Tenemos "reuniones standup" todos los días durante unos 15-20 minutos. Podemos compartir rápidamente conocimientos comunes como "Ayer hice esta función, es muy difícil".

También tenemos una wiki por proyecto. Lo que significa que podemos compartir información (técnica) sobre lo que se hace en el proyecto, incluidas las clases / funciones personalizadas que se incorporaron.

A nivel de agencia

A nivel de agencia, tenemos 4 herramientas:

  • Otra wiki Principalmente está allí para darnos información sobre hardware y otras cosas, pero a veces la usamos para compartir información técnica para revisar antes de ponerla a nivel de la compañía.
  • Reuniones semanales. En su mayoría, deben conocer el progreso de cada equipo / proyecto, pero como somos en su mayoría entusiastas de la tecnología, podemos mencionar cosas interesantes.
  • Lista de correo. Tenemos un correo con todos en la agencia. Un montón de cosas geniales / cosas divertidas / cosas útiles pasan por allí.
  • Repositorio VCS. Cada agencia tiene su repositorio personal donde tenemos pequeños proyectos, en su mayoría módulos que usamos en diferentes proyectos.

A nivel de empresa

A nivel de empresa, es más organizado.

El wiki de "nivel de agencia" es en realidad parte del wiki de la compañía.

Y la wiki luego se divide en función de las tecnologías. Por lo tanto, cualquiera puede mejorarlo, buscarlo y, básicamente, darle vida a la wiki.

También hay listas de correo disponibles a las que podemos suscribirnos. Cualquier persona en la agencia puede suscribirse, y la mayoría de las personas siguen al menos una o dos tecnologías, en realidad la mayoría de las personas siguen 5-10 de ellas.

Y el VCS es, por supuesto, el mejor sistema para compartir código.

Conclusión

En resumen, no hay una solución clara. El intercambio de conocimientos siempre ha sido un gran problema, y ​​probablemente lo seguirá siendo. Hay muchas soluciones para crear bases de conocimiento , y una probablemente podría ajustarse a su factura. Sin embargo, algunas personas están tratando de obtener una mejor KB ya que las soluciones actuales no siempre son muy inteligentes.

Florian Margaine
fuente
Siento que la conclusión no debería decir nada más que "wiki, wiki, wiki, wiki, wiki", pero en una nota seria, una buena respuesta, un wiki interno puede ser bueno para detallar detalles de mayor nivel o edad de uso, sin mencionar solo ser buscable es un buen ahorro de tiempo.
RhysW
6

Bueno, todo se reduce a la comunicación.

Los Wiki son geniales y definitivamente debes instalar y usar uno. Una buena intranet interna para programadores es buena si la gente la lee y la actualiza, por lo que en realidad estás hablando de un problema de personas allí. Podría sugerir reuniones semanales de "actualización de equipo" en las que todos se reúnan y den una visión general de qué trabajo se está realizando. Los líderes tecnológicos (¡al menos!) Deberían reunirse y conversar sobre lo que cada equipo está haciendo. Las sesiones informales de "Brown Bag" son geniales, programelas a la hora del almuerzo y haga que la gente hable.

También necesita una forma de compartir código, empaquetarlo, versionarlo y distribuirlo. Las cosas serían más fáciles si tuviera un repositorio de código fuente realmente bien administrado, bien organizado en carpetas "comunes" y de proyecto.

Si no se está haciendo nada como esto, créelo con su jefe, explique cómo beneficiará a la compañía y sugiera un camino a seguir :)

Rocklan
fuente
1
Avanzaría un poco más el concepto "común" en tu respuesta.
JeffO
4

Las sesiones de revisión de código pueden ayudar. Si su equipo se reúne regularmente para discutir lo que se desarrolló, entonces la persona que encontró una solución puede mostrar a los demás cómo usarla. Si alguien menciona un punto en el que se está aferrando, otros miembros del equipo podrían proponer un enfoque que aumente la reutilización de los componentes existentes.

Daenyth
fuente
1
¿Luego 4 años y 600 funciones más tarde cuando quieres recordar esa función que se hizo en algún momento? Parte del problema del OP fue tratar de recordar todas las cosas que se habían creado, aunque esto es bueno inicialmente, no se mantendrá durante un período de quizás, un mes o dos
RhysW
2

La mejor manera de manejar algo así es tener una estructura de repositorio que tenga algunas convenciones simples para que yo sepa, como programador, si hay una función doXYZ, más o menos dónde debería buscar esa función. Ya sea que esté utilizando espacios de nombres, directorios, módulos, complementos, paquetes, lo que sea, su código debe ser modular para que las funciones que hacen lo mismo o accedan a las mismas fuentes de datos estén en su mayoría en el mismo lugar.

Jonathan Rich
fuente
0

Idealmente, debería haber al menos otra persona además del autor haciendo una revisión del código en cada registro. El proceso de revisión del código puede ayudar a mitigar el problema de muchos métodos duplicados que se están registrando. Por supuesto, usted está limitado por el conocimiento de los revisores.

TL; DR: Revisiones de código para cada registro.

Carolina
fuente
2
No lo entiendo ¿Va a tirar el código probado y de trabajo solo porque parece un duplicado en una revisión de código? La pregunta era cómo evitar escribir el código duplicado en primer lugar. Una sesión como la respuesta de @ daenyth parece mejor.
adrianm
Si un revisor me dijera que estoy agregando código que duplica la funcionalidad, y busqué y descubrí que tienen razón, diablos, sí, desecharía el código de engaño. (Probablemente también verifique si mi implementación es mejor, y si es así, vería si puedo refactorizar la otra implementación en lugar de agregar una nueva).
Carolyn,