det är värt eller till och med nödvändigt att lägga till en README-fil i varje nytt projekt. Idag kommer vi att fokusera på god praxis att skriva en sådan fil-med några exempel och en färdig att använda mall.
vad är en README-fil?
README (som namnet antyder: ”Läs mig”) är den första filen man bör läsa när man startar ett nytt projekt. Det är en uppsättning användbar information om ett projekt och en slags handbok. En README textfil visas på många olika ställen och hänvisar inte bara till programmering., Vi kommer att fokusera på en programmerares README, dock.
exempel på README för en bootstrap pärla (Ruby On Rails)
lade README fil på GitHub visas under listan över filer i ett förråd.
om vi arbetar professionellt eller lär oss kodning, kommer vi många gånger över de offentliga arkiven. Vi använder biblioteken som gjorts tillgängliga av andra utvecklare som en öppen källkod eller vi gör vårt bidrag till ett projekt, rapportering / fastställande buggar, och lägga till nya funktioner., Visst använder vi dessa projekt eftersom de bara kommer till nytta och erbjuder en högkvalitativ lösning. Men skulle vi använda dem om de saknade en användarvänlig beskrivning, det vill säga en bra README?
var säker – du kommer att lära känna känslan av besvikelse när du hittar en potentiell lösning på alla dina problem i ett bibliotek eller ett projekt som beskrivning är dålig, värdelös eller inte är tillgänglig som helst.
vad är användningen av att skriva en bra README?
Jag tror att du kan gissa det redan., En bra README är för andra att förstå vad vår kod innehåller, och varför det är anmärkningsvärt. En README-fil är också viktigt att dra tillbaka ett projekt-på GitHub men även i webbläsare (t.ex. Google).
Jag lär mig bara så varför skulle jag bry mig om att lägga till en README-fil? Den koden är för mig, trots allt, inte för hela samhället.
Jag tvivlar på att koden bara är för dig. Och att lägga till en README-fil är ett bra drag.,
README for Junior Devs
OK, låt oss nu kolla varför vi ska ta hand om våra README-filer sedan det första projektet!
även om koden är bara för dig, kanske du kommer tillbaka till det efter ett tag. En bra README kan du starta om ett projekt – utan att slösa din tid på att påminna: vad handlade det om?
För en spirande programmerare är GitHub ett telefonkort. Projekten på GitHub är oftast vår portfölj., När vi är på ett karriärstadium utan en betydande kommersiell erfarenhet eller snygga ideella projekt är en presentation av våra prestationer i form av repositories ett av de bästa sätten att bli synliga för rekryterarna. En förberedelse av flera demonstrationsprojekt som vi vill visa upp under intervjun fungerar bäst.
om vi bara lär oss och vi släpper våra träningsprojekt där, låt oss vara uppmärksamma på deras goda beskrivning., Även en icke-teknisk rekryterare kommer att kunna känna igen den teknik vi rörde, och kontrollera om det går i linje med en kandidatens profil han/hon letar efter.
på polska eller engelska?
Visst, på engelska. Lägg till en projektbeskrivning på engelska även om ditt projekt är på polska. De projekt som realiseras vid universitetet kan behandlas som en början eftersom de ofta kräver en dokumentation på polska. Beskriv i alla andra fall dina projekt på engelska.
README.md -vad handlar det om?,
.md tillägget kommer från ett ord: markdown. Det är en markup språk för textformatering. Kanske först är det inte uppenbart men markup har skapats för att göra textskapandet enklare. På HTML-språk går den viktigaste rubriken medh1 – taggen. På samma sätt kommer vi att ha # före en rubrik i vårt dokument.
Vi redigerar .md filer i någon text eller kod redaktör (Anteckningar, Sublima, Atom -, CS, etc.).
Du hittar mer om markdown användning på GitHub, och på dillinger.,io du hittar en redaktör med en förhandsgranskning.
skriva en bra README – newbies manual
öppna en README.md. fil i ett nytt projekt.,
se till att filen alltid innehåller följande element:
- titlar och interna titlar
- Inledning – projektets syfte
- teknik
- lansering
överväga också att använda ytterligare element som:
- innehållsförteckning
- illustrationer
- omfattning av funktioner
- exempel på användning
- projektstatus
- källor
- annan information
det är mycket! Det finns inte så mycket att säga om mitt projekt!,
det finns – men du är inte medveten om det redan.
titlar och interna titlar
en titel bör tydligt förklara vad vi har här, och det är vanligtvis ett projekts namn – en H1-rubrik som är prefaced med#. Om ett projekts namn inte avslöjar innehållet är det fortfarande värt att föreslå vad det är.
dessutom bör texten innehålla titlar på sektioner och – vid behov – de interna titlarna. För att hålla vår README sammanhängande skriver vi dem på samma sätt i alla andra dokument. I vår README.,md-fil, rubrikerna ska skrivas ner med en multipel av #:
# header H1
## header H2
### header H3
#### header H4
##### header H5
###### header H6
introduktion
introduktion är som en sammanfattning. Det borde inte vara så länge vi inte vill läsa en uppsats om ett projekt. Vi bör på ett intressant sätt beskriva vad projektet syftar till, och vilka problem löser en given ansökan. Två eller tre meningar är tillräckliga vid ett litet projekt.
om det är ett utbildningsprojekt, nämn ditt incitament. Varför ville du skapa den? Att lära sig en viss teknik? Var det ett hackathon-projekt?, Var det för en ideell organisation? Är det ett program som skapats för att memorera materialet från workshops eller och online kurs? Det är värt att nämna här, utan tvekan.
Technologies
låt oss skriva ner de språk vi använde, biblioteken och dess versioner.
till exempel:
- Bootstrap 3 eller 4
- AngularJS 1.6 / Angular 2+/4/5/6
- PHP 5 eller 7
- Python 2.7 eller 3.6
- Rails 4 eller 5
Varför? För det första kommer det att vara till hjälp när projektet startas i framtiden., Versionerna av bibliotek ändras, och en inkonsekvent förändring kan orsaka många problem senare. Det är bra att veta den version som har använts när vår kod fungerade precis som vi ville ha.
en annan sak: rekrytering. Det rekryterare bläddra igenom sina kandidaters GitHub konton. Även om de saknar teknisk kunskap för att uppskatta kvaliteten på lösningarna, vet de nyckelorden relaterade till deras jobberbjudanden. En beskrivning av använd teknik kan göra att du sticker ut bland andra kandidater.,
låt oss anta att det finns en mängd kandidater för en praktik, och en rekryteringstid är begränsad. CV har valts ut, det finns två liknande kandidater och ett senast tillgängligt datum i en kalender. Kandidaternas GitHub-konton inkluderar samma antal projekt. En av dem nämner tekniken i varje projekt. En andra kandidat lägger inte till README-filer eller hans / hennes projekt beskrivs dåligt. Vad tror du, vilken kandidat kommer att bli inbjuden till en intervju?
starta
hur man kör ett projekt? Har ett projekt minimikrav på maskinvara?,
vi nämnde biblioteken och deras versioner tidigare. Om det behövs kan teknik, lansering och hårdvarukrav slås samman. Men om vi delar upp det i två underavsnitt är det värt att fokusera här specifikt på att starta ett projekt. När vi har en webbplats eller applikation kan det handla om att skapa en lokal miljö, en länk till GitHub-sidor eller distribuerad applikation på Heroku. Behöver vi indata? Om så är fallet, i vilket format?
låt oss fokusera på andra element som kan förbättra vår README.,
innehållsförteckning
innehållsförteckning är till nytta vid omfattande dokumentation. Det kan fungera som en enkel lista med länkar till rubriker.
och det kommer att se ut:
illustrationer
GitHub tillåter grafik i README. En teknisk dokumentation behöver inte vara vacker men läsbar och förståelig. Illustrationerna är inte nödvändiga – ändå kan de estetiskt värde för vårt projekt. Du kan visa en ansökan logotyp, diagram, system, exemplarisk skärmdump., Kanske är en illustrerad manual något du vill ha?
skapa en fil i arkivet och Lägg till en bild där. Använd en sökväg för att visa den med: !(ścieżka/do/pliku). Du kan använda bilderna från bortom ditt arkiv om de är tillgängliga för allmänheten – men det finns alltid en risk att ägaren till dessa källor skulle ta bort dem från sin domän, och de kommer att försvinna från din dokumentation: !(url grafiki)
exempel: i min README-fil vill jag placera ett blockschema som skulle illustrera hur en algoritm fungerar., Jag behåller schemat.jpg-fil i en katalog som heter bilder. För att visa den i min dokumentation använder jag en kod:
!(./images/schema.jpg)omfattning av funktioner
det finns ingen alltid användning för att beskriva omfattningen av funktioner. För ett webbplatsbesökskort eller en enkel tillämpning av att göra-typ är listan över funktioner ett överskott av form.,
å andra sidan kan ett till synes enkelt projekt som att göra-lista utökas med många intressanta alternativ som vi kan vara stolta över: användare registrerar, spelar in och klassificerar uppgifterna enligt datum och lägger till kommentarer till uppgifterna eller dataexporten till filerna.
exempel på användning
vid återanvändbar kod eller ditt eget bibliotek kan det vara nödvändigt att tillhandahålla en manual för hur vårt projekt ska användas., Det kan fungera som ett fragment av kod:
## Code ExamplesTo generate lorem ipsum use special shortcode: `put-your-code-here`som kommer att visas som:
projektstatusen
det är värt att lägga till en projektstatus – speciellt om projektet fortfarande utvecklas. Om det är vårt bibliotek, låt oss nämna planerade förändringar, utvecklingsriktning eller för att betona att vi är färdiga med utvecklingen.
källor
ska vi lägga till information när vårt projekt baserades på en handledning eller vi blev inspirerade med en viss uppgift? Ja, visst.
jag får inte tvivel i den delen., Det finns inget som går ut på att vi lär oss av olika källor och dokumenterar våra framsteg. Vi slutför många tutorials, välj läromedel. En tanklös kopiering utan att ge förändringar i det – och utan att lära sig alls – sker oftast inte.
om vår kod baserades på någon annans kod, bör vi lägga till sådan information.
kanske använder vi en gammal handledning – till exempel skriver vi ett program med Rails 3 handledning. Från början, i enlighet med Rails 5 version, med hjälp av nya rammekanismer. Visst är det värt att nämna här.,
När vår kod bara inspirerades av en annan lösning/ETT program kan du nämna det och skriva hur du blev inspirerad, vilka förändringar du gjorde, vilka funktioner utvecklades.
När vi löser övningarna är det värt att lägga till var andra kan hitta sin beskrivning. Om vi vill komma tillbaka till dessa källor kommer länken enkelt att komma upp. På så sätt respekteras också författaren som delade sin kunskap, tillbringade sin tid att förbereda och dela detta material.,
annan information
Information om författare, kontakt, www och sociala medier länkar, en typ av licens under vilken koden görs tillgänglig eller information om hur man bidrar till ett projekt – det här är bara exempel på vad som kan läggas till i ditt projekt.
en bra, läsbar README
förslagen ovan är mina. Den mest importaint punkten är bara läsbarhet. En grundlig dokumentation gör ditt förråd lysa framför rekryterare och andra programmerare. Det finns många sätt att skriva en bra README., Ta en titt på följande exempel:
- Node-chat – en enkel beskrivning, skärmdump av programmet, exempel på användning
- WebApp – ett utmärkt exempel på beskrivning som tillhandahålls för en målsida typ av webbplats och program med API. Beskrivning hur det fungerar, skärmdumpar, teknik som används i denna lösning, ytterligare information om funktioner som kommer att genomföras
- Pomolectron – vi har en logotyp, skärmdumpar, en instruktion om installation och en beskrivning hur det fungerar
- Git point – exemplarisk Android-applikation., En innehållsförteckning gör navigeringen enklare, skärmbilderna, nämnda funktioner och information hur man stöder programmets utveckling
README-Mall
Jag lämnar dig här ett exempel på README.md file template du kan ladda ner. Ta en titt på dess formatering, och kopiera en raw-version till din README.md arkiv.
artikeln finns även på polska på Flynerd.pl blogg.