Preparare l'intestazione pubblica per il rilascio

Question

Sono interessato a conoscere quali routine sono disponibili per la pulizia dei file di intestazione pubblica che si distribuiscono ai clienti. .

Alcune cose che mi piacerebbe sentire le vostre opinioni su sono:

Commenti non pensati per il consumo esterno. In generale mi piace tenere la documentazione vicino al codice e commenti come questo potrebbe non essere una buona idea per condividere:

/** 
* @todo Should we change the signature of this function to 
* make it obvious that xxx is really yyy? 
*/ 

o forse:

/** 
* @todo Add support for feature X 
*/ 

incoerenti Tab Stili:

void functionA(int a, 
    int b, 
    int c, 
    int d); 

void functionB(int a, 
       int b, 
       int c); 

Esistono strumenti per preparare le intestazioni o il codice in generale per il rilascio?

Answer 1

Dovresti SEMPRE, su qualsiasi progetto che coinvolge più sviluppatori per un periodo di tempo prolungato e la successiva versione di quel codice sorgente, SCANSIONE PER OSSCENITÀ (e altre cose che non dovresti aver detto, ad es. "Il mio capo mi ha fatto fai questo "," Questo codice è terribile ", ecc.). Inoltre, il controllo ortografico dei commenti può essere utile, in quanto le persone che sbagliano ortograficamente parole sono ininfluenti dalla tua credibilità.

Answer 2

Assicurarsi che le intestazioni non generino avvisi del compilatore.

Answer 3

In genere sarebbe meglio se si avessero standard di codifica/formati per i documenti che i clienti vedranno che gli stessi sviluppatori seguono quando creano il codice, quindi non passerai il tempo a ripulire il codice prima del rilascio, ad esempio ora .

Inoltre, Visual Studio e molti altri IDE dispongono di un'opzione "Auto Formattazione" in cui è possibile impostare uno stile ed è applicato al codice (schede, spazi, quel genere di cose). Penso che sia soprattutto quello che stai chiedendo qui.

Answer 4

Non ho molta familiarità con l'argomento, ma per i progetti open source hai spesso la licenza e la dichiarazione di copyright nella parte superiore dell'intestazione. Questo può evitare diversi problemi giuridici.

Answer 5

G'day,

In C++ mi piace usare il Handle-Body idiom per disaccoppiare l'attuazione quanto più possibile dall'interfaccia pubblica.

È inoltre necessario assicurarsi che qualsiasi piastra di riscaldamento, ad es. le note sul copyright, è coerente e aggiornato, ad es. il copyright non scade nel 2008 per il codice pubblicato oggi.

Essere coerenti con tutti i file di intestazione pubblici per le convenzioni di denominazione, la formattazione, il layout e il design di classe altrimenti lascia un'impressione non professionale sui clienti.

Assicurarsi che non ci siano dichiarazioni "uso" nei file di intestazione. L'uso improprio di "usare" dec's può seriamente rovinare tutto con effetti collaterali involontari.

Come accennato in precedenza, assicurarsi che le intestazioni non generino eventuali avvisi.

Infine. assicurati di avere una buona documentazione API da usare con i tuoi file header.

Non essere come una società che fornisce un noto prodotto di ricerca codice postale. La prima versione dell'API C è stata fornita con una documentazione minima basata principalmente sulla versione della GUI di Windows. I file di intestazione consistevano semplicemente in funzioni i cui parametri avevano solo tipi e nessun nome. E no commenti a tutti.

L'unico modo per capire che cosa effettivamente hanno fatto le funzioni era di decodificare un semplice esempio di programma di ricerca fornito e decodificarlo.

Eppure, dopo essermi riuscito a farlo, ho salvato i bambini bisognosi della Bbc decine di migliaia di sterline l'anno perché gli indirizzi previsti per i pacchetti di raccolta fondi erano più probabili di essere corretti rispetto agli anni precedenti!

Answer 6

Nella mia esperienza l'utilizzo di un'intestazione utilizzata internamente, ordinariamente e automaticamente ripulita per il consumo pubblico, è un compito difficile e sicuramente soggetto a errori. Alla fine il formato incoerente o il commento inappropriato sarà inevitabilmente insinuarsi.

In molti casi è preferibile spostare tutto in un'interfaccia piccola e pulita, il cui header viene sempre mantenuto il più pulito e il più commentato possibile; le modifiche a tale file devono essere sottoposte, ad esempio, a un processo di revisione particolarmente attento.

Answer 7

Altrettanto importante come la rimozione di commenti crufty è l'aggiunta di quelli necessari. Cose che si potrebbe essere necessario aggiungere:

• copyright/termini di utilizzo di intestazione
informazioni
• di contatto per il supporto
• collegamenti alla documentazione se viene reso disponibile online
• documentazione delle interfacce pubbliche (ritorno valori, parametri, pre e post-condizioni, ecc)
• avvertenze sulle funzioni/metodi che sono esposti, ma non destinati ad uso di produzione

Answer 8

Sempre avere qualcuno (preferibilmente più di uno) passare attraverso l'intestazione per cercare qualcosa che sembra poco professionale. È possibile utilizzare prima i formattatori di codice e altri strumenti automatici.

Per i commenti, invitali a cercare qualcosa di non professionale o di prova. Correggere gli errori ortografici. Assicurati che siano precisi. Avere un modo standard per formattarli e attenersi ad esso.

Controllare tutti i nomi degli identificatori. Dovrebbero conformarsi a una guida di stile e essere nominati professionalmente.

assicurarsi che tutti i commenti necessari ci sono. Questo include copyright e informazioni di contatto in alto. Vieni con un metodo standard per documentare le classi e simili, e applicarlo.

Fondamentalmente, dal mio punto di vista, vuoi che le tue intestazioni sembrino prodotte da droni senza creatività o senso dell'umorismo, ma che siano perfettamente coerenti (una specie di stereotipi CPA simili). (È come chiedere ai tuoi sviluppatori di indossare abiti mentre i clienti visitano l'ufficio: i clienti saranno più felici se non vedranno realmente i tuoi sviluppatori.)