Come tieni traccia di quali classi e funzioni ha scritto il tuo team?


43

Quando lavoro sul codice, devo affrontare molte delle stesse sfide che i miei compagni di squadra fanno, e ho scritto alcune utili funzioni e classi, e anche loro. Se c'è una buona comunicazione, sentirò parlare di qualcosa di eccezionale che qualcuno ha messo insieme, e sei mesi dopo, quando ne avrò bisogno, me lo ricorderò e chiamerò quella funzione, risparmiando tempo. Se non me lo ricordo, o non l'ho mai saputo, probabilmente reinventerò la ruota.

Esiste una pratica particolare per documentare questo tipo di cose? Come li rendi facili da trovare?

Se la tua squadra non ha tale documentazione, come fai a sapere se la tua ruota esiste già?

MODIFICARE:

Finora tutte le risposte tranne una hanno a che fare con una situazione ideale, quindi vorrei riassumere quelle soluzioni: documentazione e comunicazione; wiki, stand-up meeting, ecc. Queste sono tutte cose fantastiche, ma si affidano ai programmatori che hanno il tempo (e le competenze) di scrivere la documentazione e partecipare alle riunioni e prendere appunti e ricordare tutto.

La risposta più popolare finora (quella di Caleb) è l'unica che potrebbe essere utilizzata da un programmatore incapace di documentazione e riunioni e che fa solo una cosa: la programmazione. La programmazione è ciò che fa un programmatore, e sì, un grande programmatore può scrivere documentazione, unit test, ecc., Ma ammettiamolo: la maggior parte di noi preferisce programmare alla documentazione. La sua soluzione è quella in cui il programmatore riconosce il codice riutilizzabile e lo estrae nella propria classe o repository o altro, e dal fatto che è isolato, diventa reperibile e facilita la curva di apprendimento per usarlo ... e ciò è stato realizzato mediante la programmazione.

In un certo senso la vedo così: ho appena scritto tre funzioni e mi viene in mente che qualcun altro dovrebbe conoscerle. Potrei documentarli, scriverli, annunciarli in una riunione, ecc. - cosa che posso fare, ma non è la mia forza - o ... Posso estrarli in una classe, nominarlo bene, farli funzionare come una scatola nera e incollala dove vanno gli altri file di classe. Quindi una breve email che lo annuncia è facile. Altri sviluppatori possono eseguire la scansione del codice e comprenderlo meglio di quanto potrebbero utilizzare una funzione isolata utilizzata nel codice che non comprendono appieno: tale contesto viene rimosso.

Mi piace perché significa che avere una serie di file di classe ben denominati, con metodi ben nominati, è una buona soluzione che si ottiene con una buona programmazione. Non richiede riunioni e attenua la necessità di una documentazione dettagliata.

Ci sono altre idee in questa vena ... per sviluppatori isolati e costretti a perdere tempo?


5
Vorrei espandere la domanda da porre su una scala più ampia, forse in una società di oltre 100 dipendenti come si fa a fare lo stesso. Quali sono le migliori pratiche per evitare la duplicazione del lavoro svolto in precedenza?
Asaf

1
@Asaf - Sospetto che la risposta corretta dipenda dalle dimensioni della popolazione - ciò che funziona per un negozio di 5 persone non funzionerà per 50 e ciò che funziona per 50 non funzionerà per 500. Le risposte a tutti sarebbero benvenute.
Dan Pichelman,

3
Questa è un'ottima domanda!
Rocklan,

4
Legge di Conway : "le organizzazioni che progettano sistemi ... sono costrette a produrre progetti che sono copie delle strutture di comunicazione di queste organizzazioni".
Mark Rushakoff,

2
@nathanhayfield: questa è una soluzione che può funzionare per 1 sviluppatore, e in una certa misura per 2, ma non per 20 o 100. E anche quando lavoro da solo, preferisco separare tematicamente le funzioni di supporto.
Doc Brown,

Risposte:


29

Biblioteche. Framework. Controllo della versione.

Se hai un codice riutilizzabile, l'ultima cosa che desideri è che diversi membri del team copino il codice sorgente nel loro progetto. Se lo fanno, è probabile che cambieranno un po 'qui e modificheranno un po' lì, e presto avrai dozzine di funzioni o metodi che hanno tutti lo stesso nome ma che funzionano in modo leggermente diverso. O, forse più probabilmente, l'autore originale continuerà a perfezionare il codice per correggere bug, renderlo più efficiente o aggiungere funzionalità, ma il codice copiato non verrà mai aggiornato. Il nome tecnico per questo è un casino enorme .

La soluzione giusta è quella di estrarre quella roba riutilizzabile da qualunque progetto tu l'abbia creata in primo luogo e metterla in una libreria o framework nel suo repository di controllo della versione. Questo lo rende facile da trovare, ma scoraggia anche apportare modifiche senza considerazione per tutti gli altri progetti che potrebbero usarlo. Potresti considerare di avere diverse librerie diverse: una per codice ben collaudato che non è più probabile che cambi, una per cose che sembrano stabili ma che non sono state testate e riviste a fondo, una per le aggiunte proposte.


5
Vorrei anche raccomandare di avere un set molto completo di test di regressione per la libreria riutilizzabile. Anche se il cambiamento sembra innocuo, qualcuno potrebbe dipendere da quel comportamento.
Bobson,

2
Pensavo che il termine tecnico fosse BBOM .
zzzzBov

2
La tua risposta sembra ragionevole a prima vista, e su scala da piccola a media è, ma ho anche visto il lato oscuro di una direttiva "non copiare". Se disponi di team diversi per prodotti diversi, con termini di licenza, cicli di vita e contratti di manutenzione diversi, l' ultima cosa che desideri è accoppiare i diversi prodotti a una libreria di frammenti di codice prodotta in casa che non corrisponda a tali requisiti di manutenzione . Le librerie per quel tipo di scenario devono avere una qualità molto elevata, e talvolta è persino più efficace per una squadra copiare il codice e ...
Doc Brown,

3
@Caleb: stai calmo, leggi il mio post completamente. Il mio punto è: copiare il codice da qualche altra parte, modificarlo e integrarlo nella libreria di un team non ti porta necessariamente sulla "strada della perdizione". Quando hai due librerie con funzionalità sovrapposte e due squadre da cui ognuna è responsabile del mantenimento della propria libreria, la situazione non è poi così grave. Non è perfetto, dal momento che una squadra può fare un po 'di lavoro anche l'altra, ma a volte il vantaggio che quelle squadre continuano a essere indipendenti supera il doppio lavoro.
Doc Brown,

1
@DocBrown Ci sono situazioni in cui diventa necessario copiare il codice, ma quella dovrebbe essere una decisione consapevole e non qualcosa che sei costretto a fare a causa del modo in cui il codice è stato condiviso in primo luogo.
Caleb,

13

Un approccio per questo è creare un Wiki a tale scopo e scrivere alcuni documenti di alto livello su quali componenti riutilizzabili hai, come hai risolto un problema, ecc.

La parte difficile è convincere tutti nella tua squadra a mantenere costantemente quel Wiki. Ma qualsiasi altro tipo di documentazione soffre dello stesso problema.

Parte del codice potrebbe anche essere abbastanza buono da essere inserito in una libreria riutilizzabile. Ciò semplifica anche la ricerca del codice in un secondo momento.


5
Una wiki non è il modo giusto per diffondere il codice. È un ottimo modo per comunicare sul codice, ma (vedi la mia risposta) non vuoi che le persone copino qualcosa di più grande di uno snippet da un wiki e lo incollino nel loro progetto.
Caleb,

@Caleb la comunicazione è la parte difficile
jk.

@jk - I problemi di comunicazione si aggravano se non si ha il controllo del codice sorgente menzionato in C
JeffO

3
@Caleb: la domanda del PO non riguardava la diffusione del codice, la domanda riguardava la comunicazione e la ricerca in un secondo momento.
Doc Brown,

@DocBrown Ancora una volta, i wiki sono ottimi per comunicare, ed è probabilmente per questo che strumenti come GitHub ne hanno uno incorporato. Ma la cosa che rende facile trovare il codice non è che è menzionato in un wiki, è che è conservato in un luogo noto. Questo potrebbe essere un wiki, ma se stiamo parlando di codice che le persone sono in realtà intenzione di utilizzare (a fronte di un mucchio di frammenti che illustrano una soluzione) che dovrebbe essere una libreria di qualche tipo, qualcosa che è edificabile, verificabile, e che può essere incorporato senza moltiplicare il numero di luoghi in cui prima o poi dovrà essere aggiornato.
Caleb,

7

Essere in un'azienda con 700 dipendenti, all'interno di team che variano da 2 a 20 persone, ecco la mia esperienza.

A livello di squadra

Abbiamo "incontri standup" ogni giorno per circa 15-20 minuti. Possiamo rapidamente condividere conoscenze comuni come "Ho fatto questa funzione ieri, è così difficile".

Abbiamo anche un wiki per progetto. Ciò significa che possiamo condividere informazioni (tecniche) su ciò che è stato fatto nel progetto, comprese le classi / funzioni personalizzate integrate.

A livello di agenzia

A livello di agenzia, abbiamo 4 strumenti:

  • Un'altra wiki. È principalmente lì per darci informazioni su hardware e cose, ma a volte le usiamo per condividere informazioni tecniche da rivedere prima di metterle a livello aziendale.
  • Incontri settimanali. Devono principalmente conoscere i progressi di ogni squadra / progetto, ma dal momento che siamo per lo più appassionati di tecnologia, possiamo tirar fuori cose interessanti.
  • Mailing list. Abbiamo un mailing con tutti in agenzia. Ci sono un sacco di cose interessanti / cose divertenti / cose utili.
  • Repository VCS. Ogni agenzia ha il suo repository personale in cui abbiamo piccoli progetti, principalmente moduli che utilizziamo in diversi progetti.

A livello aziendale

A livello aziendale, è più organizzato.

Il wiki "a livello di agenzia" fa effettivamente parte del wiki dell'azienda.

E il wiki viene quindi suddiviso in base alle tecnologie. Pertanto, chiunque può migliorarlo, cercarlo e fondamentalmente dare vita al wiki.

Ci sono anche mailing list disponibili a cui possiamo iscriverci. Chiunque nell'agenzia può iscriversi e la maggior parte delle persone segue almeno una o due tecnologie, in realtà la maggior parte delle persone ne segue 5-10.

E il VCS è ovviamente il miglior sistema di condivisione del codice.

Conclusione

Per riassumere, non esiste una soluzione chiara. La condivisione della conoscenza è sempre stata un grosso problema e probabilmente rimarrà. Esistono molte soluzioni per creare basi di conoscenza e una potrebbe probabilmente adattarsi al conto. Tuttavia, alcune persone stanno cercando di ottenere KB ancora migliori poiché le soluzioni attuali non sono sempre molto intelligenti.


Sento che la conclusione non dovrebbe dire altro che "wiki, wiki, wiki, wiki, wiki" ma su una nota seria, buona risposta, un wiki interno può essere buono per dettagliare dettagli di livello superiore o età d'uso, per non parlare solo essere ricercabili è un buon risparmio di tempo.
RhysW,

6

Bene, tutto si riduce alla comunicazione.

I wiki sono fantastici e dovresti assolutamente installarne e utilizzarne uno. Una buona intranet di programmatori interni è buona se le persone lo leggono e lo aggiornano, quindi in realtà stai parlando di un problema di persone lì. Puoi suggerire riunioni settimanali di "aggiornamento del team" in cui tutti si riuniscono e offrono una panoramica di ciò che il lavoro sta svolgendo. I leader tecnologici (almeno!) Dovrebbero stare insieme e chattare su ciò che ogni squadra sta facendo. Le sessioni informali di "Brown Bag" sono fantastiche, programmale all'ora di pranzo e fai parlare le persone.

È inoltre necessario un modo per condividere il codice, impacchettarlo, verificarlo e distribuirlo. Le cose sarebbero più facili se si avesse un repository di codice sorgente davvero ben gestito, ben organizzato in cartelle "comuni" e di progetto.

Se non si sta facendo nulla del genere, portalo con il tuo capo, spiega come andrà a beneficio dell'azienda e suggerisci una via da seguire :)


1
Vorrei spostare ulteriormente il concetto "comune" nella tua risposta.
JeffO,

4

Le sessioni di revisione del codice possono aiutare. Se il tuo team si incontra regolarmente per discutere di ciò che è stato sviluppato, la persona che ha trovato una soluzione può mostrare agli altri come usarla. Se qualcuno evidenzia un punto su cui si attengono, gli altri membri del team potrebbero proporre un approccio che aumenta il riutilizzo dei componenti esistenti.


1
Quindi 4 anni e 600 funzioni dopo, quando vuoi ricordare quella funzione che è stata fatta da tempo? Parte del problema del PO consisteva nel cercare di ricordare tutte le cose che erano state create, mentre inizialmente è una cosa buona che non
reggerà

2

Il modo migliore per gestire qualcosa del genere è avere una struttura di repository che abbia alcune semplici convenzioni in modo che io sappia, come programmatore, se esiste una funzione doXYZ, all'incirca dove dovrei cercare quella funzione. Indipendentemente dal fatto che tu stia utilizzando spazi dei nomi, directory, moduli, plug-in, pacchetti, qualunque cosa, il tuo codice dovrebbe essere modulare in modo che le funzioni che fanno la stessa cosa o accedono alle stesse fonti di dati siano quasi sempre nello stesso posto.


0

Idealmente, ci dovrebbe essere almeno un'altra persona oltre all'autore che fa una revisione del codice ad ogni check-in. Il processo di revisione del codice può aiutare a mitigare il problema di molti metodi duplicati che vengono archiviati. Naturalmente, sei limitato dalla conoscenza dei revisori.

TL; DR: revisioni del codice per ogni check-in.


2
Non capirlo. Butterai via il codice testato e funzionante solo perché sembra un duplicato in una revisione del codice? La domanda era come evitare di scrivere il codice duplicato in primo luogo. Una sessione come la risposta di @ daenyth sembra migliore.
Adrianm,

Se un revisore mi ha detto che sto aggiungendo un codice che duplica la funzionalità e ho cercato e scoperto che hanno ragione, diamine sì, eliminerei il codice duplicato. (Probabilmente verificherei anche se la mia implementazione è migliore e, in tal caso, vedere se potrei refactoring l'altra implementazione invece di aggiungerne una nuova.)
Carolyn,
Utilizzando il nostro sito, riconosci di aver letto e compreso le nostre Informativa sui cookie e Informativa sulla privacy.
Licensed under cc by-sa 3.0 with attribution required.