Suggerimenti per un fantastico file readme (e perché questo è importante)
Noi, gli sviluppatori, sono molto buoni con il codice e tutti i dettagli dei nostri progetti. Ma alcuni di noi (me incluso) mancano di soft-skills anche nella comunità online.,
Uno sviluppatore impiegherebbe un’ora a regolare il padding e il margine di un singolo pulsante. Ma non risparmierebbe 15 minuti per il file Readme della descrizione del progetto.
Spero che la maggior parte di voi sappia già cosa readme.md il file è e a cosa serve. Ma per i neofiti qui cercherò di spiegare di cosa si tratta esattamente.
Che cosa è un Readme.md?
README (come suggerisce il nome: “read me”) è il primo file che si dovrebbe leggere quando si avvia un nuovo progetto., È un insieme di informazioni utili su un progetto e una sorta di manuale. È il primo file che Github o qualsiasi sito di hosting Git mostrerà quando qualcuno apre il tuo repository..
Come si può chiaramente vedere qui Readme.md file nella radice del repository e viene visualizzata automaticamente da github sotto la directory del progetto.
E l’estensione.mdderiva da una parola: markdown., È un linguaggio di markup per la formattazione del testo. Proprio come HTML è un linguaggio di markup per rendere i nostri documenti presentabili.
Ecco un esempio di un file markdown e come viene visualizzato su github in realtà. Io uso VSCode qui per l’anteprima che mostra un’anteprima dei file markdown contemporaneamente.
Qui è un ufficiale di Github cheat sheet per il formato Markdown se avete bisogno di abitare in profondità nella lingua.
Ora parliamo di affari., Hai passato ore su un progetto, l’hai reso pubblico su GitHub e vuoi persone/reclutatori/colleghi / (Ex?) vedi il tuo progetto. Pensi davvero che andrebbero in root/src/app/main.js per visualizzare quella tua bella logica? Sul serio?
Ora che ho la vostra attenzione, vediamo come affrontare questo.
Generare documentazione per i tuoi componenti
Oltre al readme del tuo progetto, documentare i tuoi componenti è fondamentale per una base di codice comprensibile. Rende molto più facile riutilizzare i componenti e mantenere il codice., Utilizzare strumenti come Bit (Github) per generare automaticamente la documentazione per i componenti condivisi su bit.dev
Descrivi il tuo progetto! (TL; DR)
Scrivi una buona descrizione dei tuoi progetti. Solo per le linee guida, puoi formattare la tua descrizione nei seguenti argomenti: –
- Titolo (anche un’immagine del titolo se possibile-modificali su canva.,com se non sei un graphic designer.)
- Descrizione(Descrivi con parole e immagini)
- Demo (Immagini, link video, link Demo live)
- Tecnologie utilizzate
- Trucchi speciali dei tuoi progetti (problemi che hai affrontato, elementi unici del tuo progetto)
- Descrizione tecnica del tuo progetto come – Installazione, installazione, come contribuire.
Immergiamoci in profondità negli aspetti tecnici
Userò questo mio progetto come riferimento, che penso abbia uno dei più bei file readme che ho scritto e persino incontrato., È possibile controllare il codice del file Readme.md file qui di seguito:
Utilizzare l’icona a forma di matita per mostrare il codice markdown :-
aggiunta di IMMAGINI! PER FAVORE!
Potresti avere una memoria fotografica ma i tuoi lettori potrebbero aver bisogno di alcune fotografie reali della demo del tuo progetto.
Ad esempio, ho creato un progetto di solitario e ho aggiunto le immagini come descrizione nel readme.,
Now you may want to add a video description of your projects too. Just like I did. BUT… Github doesn’t let you add a video to the readme… So… So what?
…WE USE GIFS
Le Gif rientrano nella categoria delle immagini e github ti consente di averle sul tuo readme.
Il Distintivo d’onore
Badge sul readme dare allo spettatore una certa sensazione di autenticità., È possibile ottenere personalizzate/usato regolarmente scudi(badge) per il repository da:- https://shields.io
Si può anche ottenere personalizzato scudi come il numero di stelle sulla repo e codice percentuale indicatori di troppo.
Aggiungere una demo dal vivo
Se possibile ottenere il vostro progetto ospitato e impostare una demo in esecuzione. Dopo di che COLLEGA QUESTA DEMO AL TUO README., Non hai idea di quante persone potrebbero finire per giocare con i tuoi progetti. E reclutatore solo AMORE progetti dal vivo. Mostra che i tuoi progetti non sono solo una discarica di codice su github e in realtà fai sul serio.
È possibile utilizzare i collegamenti Ipertestuali nel Readme. Quindi, dare un link Demo dal vivo appena sotto l’immagine del titolo.
Usa la formattazione del codice
Markdown ti dà la possibilità di formattare il testo come codice., Quindi non scrivere codice come testo normale invece usa ‘ (Tilde) per avvolgere il codice all’interno della formattazione del codice in quanto tale- var a = 1;
Github ti dà anche la possibilità di specificare la lingua in cui è scritto il codice in modo che possa utilizzare l’evidenziazione del testo specifico per rendere il codice più leggibile. Per fare ciò utilizzare
“{language-extension}<spazio>{Code block Inside}“
{ “ }- La tripla tilde viene utilizzata per il codice a più righe e consente anche di specificare la lingua del blocco di codice.,
With Language Highlighting:-
Without Langage Highlighting:-
Use of HTML
Yes, you can use HTML inside. Not all the features though. But most of it., Anche se si dovrebbe attenersi a markdown solo ma, alcune caratteristiche come centrare le immagini e il testo nel readme è possibile solo da HTML.
Lascia un commento