Domande taggate «documentation»

Molte persone affermano che "i commenti dovrebbero spiegare" perché ", ma non" come "". Altri affermano che "il codice dovrebbe essere auto-documentante" e che i commenti dovrebbero essere scarsi. Robert C. Martin afferma che (riformulato alle mie stesse parole) spesso "i commenti sono scuse per il codice scritto male". La …

236 programming-practices  documentation  comments 

Mi è stato specificamente chiesto di fornire spiegazioni riga per riga (o, se del caso, ad esempio immagine per immagine, ecc.) Che il mio capo vuole essere in grado di leggere e seguire. Dal momento che non è un programmatore, non può seguire il codice, quindi vuole che tutto sia …

155 documentation 

Lo standard RFC 2606 si riserva i nomi di dominio example.org , example.net ed example.com allo scopo di essere usati come esempi nella documentazione. Qual è l'equivalente di un numero di telefono (incluso il prefisso internazionale) che può essere utilizzato come esempio, ad esempio per fornire agli utenti un esempio …

112 documentation  standards  help-documentation 

Supponiamo che stia sviluppando un progetto relativamente grande. Ho già documentato tutte le mie classi e funzioni con Doxygen, tuttavia, ho avuto l'idea di mettere un "note del programmatore" su ogni file di codice sorgente. L'idea alla base è quella di spiegare in parole povere come funziona una classe specifica …

104 documentation  large-scale-project 

Durante una riunione riguardante il rollback di un SDK di terze parti dall'ultima versione, è stato notato che i nostri sviluppatori hanno già segnalato nella cronologia del commit che l'ultima versione non deve essere utilizzata. Alcuni sviluppatori hanno sostenuto che si trattava di una cattiva pratica e che avrebbe dovuto …

94 version-control  documentation 

Sto lavorando a un progetto abbastanza grande e ho il compito di fare alcune traduzioni per questo. C'erano tonnellate di etichette che non sono state tradotte e mentre cercavo il codice ho trovato questo piccolo pezzo di codice //TODO translations Questo mi ha fatto pensare al senso di questi commenti …

86 documentation  comments 

Ho scritto il seguente codice: if (boutique == null) { boutique = new Boutique(); boutique.setSite(site); boutique.setUrlLogo(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getLogo()); boutique.setUrlBoutique(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getUrl()); boutique.setNom(fluxBoutique.getNom()); boutique.setSelected(false); boutique.setIdWebSC(fluxBoutique.getId()); boutique.setDateModification(new Date()); boutiqueDao.persist(boutique); } else { boutique.setSite(site); boutique.setUrlLogo(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getLogo()); boutique.setUrlBoutique(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getUrl()); boutique.setNom(fluxBoutique.getNom()); //boutique.setSelected(false); boutique.setIdWebSC(fluxBoutique.getId()); boutique.setDateModification(new Date()); boutiqueDao.merge(boutique); } C'è una linea commentata qui. Ma penso che renda il codice più chiaro, rendendo …

83 documentation  comments 

Prima di tutto, in questa domanda vorrei stare lontano dalla polemica sul fatto che commentare il codice sorgente sia positivo o negativo. Sto solo cercando di capire più chiaramente cosa intendono le persone quando parlano di commenti che ti dicono PERCHÉ, COSA o COME. Spesso vediamo linee guida come "I …

78 documentation  comments 

Tre mesi fa stavo lavorando a un progetto, poi improvvisamente è apparso un altro progetto urgente e mi è stato chiesto di spostare la mia attenzione. A partire da domani, tornerò al vecchio progetto. Mi rendo conto di non ricordare cosa stavo facendo esattamente. Non so da dove cominciare. Come …

72 project-management  documentation 

Sto pensando di lasciare il mio attuale lavoro perché siamo bloccati nell'uso di Blub , con un framework Blub aziendale e un server Web di livello Blub, su un hosting condiviso mediocre. I miei colleghi sono amichevoli e il mio capo è un piccolo imprenditore medio - voglio partire interamente …

66 career-development  documentation 

Comprendo l'importanza di un codice ben documentato. Ma capisco anche l'importanza del codice auto-documentante . Più è facile leggere visivamente una particolare funzione, più velocemente possiamo passare durante la manutenzione del software. Detto questo, mi piace separare le grandi funzioni da altre più piccole. Ma lo faccio fino al punto …

63 programming-practices  code-quality  documentation 

La generazione automatica della documentazione può essere eseguita con una varietà di strumenti, tra cui GhostDoc è uno dei più importanti. Tuttavia, per definizione, tutto ciò che genera è ridondante. Dà un'occhiata a nomi di metodi, classi, ecc . E mostra l' inglese che potrebbe spiegarli in modo più dettagliato. …

60 documentation  automation  automatic-programming 

Sto scrivendo documentazione per l'utente (un SOP) che coinvolge programmi di terze parti che sto cercando di descrivere bene. Uno di questi programmi è un server che offre poche indicazioni sul suo avvio oltre a un grafico che mostra durante la sua routine di inizializzazione / avvio. Come sviluppatore, ho …

59 documentation  component  jargon 

A volte mi trovo in situazioni in cui la parte di codice che sto scrivendo è (o sembra essere ) così evidente che il suo nome sarebbe sostanzialmente ripetuto come un commento: class Example { /// <summary> /// The location of the update. /// </summary> public Uri UpdateLocation { get; …

54 programming-practices  documentation  language-agnostic 

Quando usi strumenti come jsdocs , genera file HTML statici e i suoi stili nella base di codice in base ai commenti nel codice. Questi file dovrebbero essere archiviati nel repository Git o dovrebbero essere ignorati con .gitignore?

49 git  documentation