Det er værd eller endda nødvendigt at tilføje en README-fil i hvert nyt projekt. I dag vil vi fokusere på god praksis med at skrive en sådan fil – med et par eksempler og en klar til brug skabelon.
Hvad er en README-fil?
README (som navnet antyder: “Læs mig”) er den første fil, man skal læse, når man starter et nyt projekt. Det er et sæt nyttige oplysninger om et projekt og en slags manual. En README-tekstfil vises mange forskellige steder og henviser ikke kun til programmering., Vi vil dog fokusere på en programmers README.
eksempel på brug for en Bootstrap perle (Ruby On Rails)
Tilføjet README-filen på GitHub vises under listen af filer i et arkiv.
Hvis vi arbejder professionelt eller lærer kodning, støder vi mange gange på de offentlige lagre. Vi bruger Bibliotekerne, der stilles til rådighed af andre udviklere som en open source-kode, eller vi bidrager til et projekt, rapporterer / retter fejl og tilføjer nye funktionaliteter., Vi bruger bestemt disse projekter, fordi de bare kommer godt med og tilbyder en løsning af høj kvalitet. Men ville vi bruge dem, hvis de manglede en brugervenlig Beskrivelse, Det vil sige en god README?
vær sikker på – du vil lære følelsen af skuffelse at kende, når du finder en potentiel løsning på alle dine problemer i et bibliotek eller et projekt, som beskrivelse er dårlig, ubrugelig eller ikke er tilgængelig overhovedet.
Hvad er brugen af at skrive en god README?
Jeg tror, du kan gætte det allerede., En god README er for andre at forstå, hvad vores kode indeholder, og hvorfor det er bemærkelsesværdigt. En README-fil er også vigtig for at genoptage et projekt – på GitHub, men også i Bro .sere (f.eks.
Jeg lærer bare, så hvorfor skulle jeg være generet af at tilføje en README-fil? Denne kode er bare for mig, trods alt, ikke for hele samfundet.
Jeg tvivler på, at koden kun er til dig. Og at tilføje en README-fil er et godt træk.,
README for Junior Devs
OK, lad os nu kontrollere, hvorfor vi skal passe på vores README-filer siden det første projekt!
selvom koden kun er til dig, vil du muligvis komme tilbage til den efter et stykke tid. En god README giver dig mulighed for at relancere et projekt – uden at spilde din tid på at huske: hvad handlede det om? for en spirende programmør er GitHub et telefonkort. Projekterne på GitHub er oftest vores portefølje., Når vi er på en karriere på scenen uden en betydelig kommerciel erfaring eller nice-leder non-profit projekter, en præsentation af vores resultater i form af depoter er en af de bedste måde at få synlig for personalekonsulenter. En forberedelse af flere demonstrationsprojekter, vi vil vise frem under intervie .et, fungerer bedst.
hvis vi bare lærer, og vi slipper vores træningsprojekter der, lad os være opmærksomme på deres gode beskrivelse., Selv en ikke-teknisk rekrutterer vil være i stand til at genkende de teknologier, vi rørte ved, og kontrollere, om det går i overensstemmelse med en kandidats profil, han/hun leder efter.
på polsk eller engelsk?
bestemt på engelsk. Tilføj en projektbeskrivelse på engelsk, selvom dit projekt er på polsk. De projekter, der blev realiseret på universitetet, kan behandles som en e .eption, da de ofte kræver dokumentation på polsk. I alle andre tilfælde skal du beskrive dine projekter på engelsk.
README.md -hvad handler det om?,
.md udvidelse kommer fra et ord: markdo .n. Det er et markeringssprog til tekstformatering. Måske i starten er det ikke indlysende, men markup er oprettet for at gøre tekstoprettelse lettere. I HTML-sprog går den vigtigste overskrift med h1 tag. På samme måde vil vi have # før en overskrift i vores dokument.
vi redigerer .md filer i enhver tekst-eller kodeditor (Notesblok, Sublime, Atom, CS osv.).
Du kan finde ud af mere om markdo .n brug på GitHub, og på dillinger.,io finder du en editor med en forhåndsvisning.
skrivning af en god README-ne newbies manual
Åbn a README.md. fil i et nyt projekt.,
sørg for, at filen altid indeholder følgende elementer:
- Titler og interne titler
- Introduktion – projektets formål
- Teknologier
- Start
Overvej også ved hjælp af yderligere elementer som:
- indholdsfortegnelse
- Illustrationer
- Omfanget af funktionaliteter
- Eksempler på brug
- Projektets status
- Kilder
- Andre oplysninger
Der er en masse! Der er ikke så meget at sige om mit projekt!,
Der er – men du er ikke klar over det allerede.
Titler og interne titler
En titel skal forklare tydeligt, hvad vi har her, og det er normalt et projekt, navn – en H1 overskrift indledes med #. Hvis et projekts navn ikke afslører dets indhold, er det stadig værd at foreslå, hvad det er.
desuden skal teksten indeholde titlerne på sektioner og – om nødvendigt – de interne titler. For at holde vores README sammenhængende skriver vi dem på samme måde i hvert andet dokument. I vores README.,md-fil, overskrifter skal skrives ned med flere af #:
# header H1
## header H2
### header H3
#### header H4
##### header H5
###### header H6
Indledning
Indledning er som en sammenfatning. Det bør ikke være for længe, da vi ikke ønsker at læse et essay om et projekt. Vi bør på en interessant måde beskrive, hvad der er projektets mål, og hvilke problemer løser en given applikation. To eller tre sætninger er nok i tilfælde af et lille projekt.
Hvis det er et træningsprojekt, skal du nævne dit incitament. Hvorfor ville du oprette det? At lære en bestemt teknologi? Var det et hackathon-projekt?, Var det for en non-profit organisation? Er det et program skabt til at huske materialet fra workshopsorkshops eller og online kursus? Det er værd at nævne her uden tvivl.
teknologier
lad os skrive ned de sprog, vi brugte, bibliotekerne og dens versioner.
For eksempel:
- Bootstrap 3 eller 4
- AngularJS 1.6 / Vinklet 2+/4/5/6
- PHP 5 eller 7
- Python 2.7 eller 3,6
- Skinner, 4 eller 5
Hvorfor? For det første vil det være nyttigt, når projektet lanceres i fremtiden., Versionerne af biblioteker ændres, og en iøjnefaldende ændring kan forårsage mange problemer senere. Det er godt at kende den version, der er blevet brugt, da vores kode fungerede nøjagtigt som vi ønskede.
en anden ting: rekruttering. IT-rekrutterere gennemser deres kandidaters GitHub-konti. Selvom de mangler en teknisk viden til at estimere kvaliteten af løsninger, kender de nøgleordene relateret til deres jobtilbud. En beskrivelse af brugte teknologier kan få dig til at skille dig ud blandt andre kandidater.,
lad os antage, at der er et væld af kandidater til en praktikplads, og en rekrutteringstid er begrænset. Der er valgt CV ‘ er, der er to ens kandidater, og en sidste tilgængelig dato i en kalender. Kandidaternes GitHub-konti inkluderer det samme antal projekter. En af dem nævner teknologierne i hvert projekt. En anden kandidat tilføjer ikke README-filer, eller hans / hendes projekter beskrives Dårligt. Hvad tror du, hvilken kandidat vil blive inviteret til et intervie??
Start
Sådan køres et projekt? Har et projekt minimum hard ?arekrav?,
vi nævnte bibliotekerne og deres versioner tidligere. Om nødvendigt kan teknologier, lancering og Hard .arekrav flettes sammen. Men hvis vi opdeler det i to underafsnit, er det værd at fokusere her specifikt på at lancere et projekt. Når vi har et websiteebsted eller en applikation, kan det vedrøre opsætning af et lokalt miljø, et link til GitHub-sider eller en implementeret applikation på Heroku. Har vi brug for inputdata? Hvis ja, i hvilket format?
lad os fokusere på andre elementer, der kan forbedre vores README.,
indholdsfortegnelse
indholdsfortegnelse er praktisk i tilfælde af omfattende dokumentation. Det kan fungere som en simpel liste med links til overskrifter.
Og det vil se ud som dette:
Illustrationer
GitHub giver mulighed for grafik i README. En teknisk dokumentation behøver ikke at være smuk, men læselig og forståelig. Illustrationerne er ikke nødvendige – ikke desto mindre kan de æstetisk værdi for vores projekt. Du kan vise et programs logo, diagrammer, ordninger, eksemplarisk skærmbillede., Måske er en illustreret manual noget, du vil have?
Opret en fil i dit arkiv, og tilføj et billede der. Brug en filsti til at vise den ved hjælp af: !(ścieżka/do/pliku). Du kan bruge billeder fra ud over dig arkiv, hvis de er offentligt tilgængelige – men der er altid en risiko for, at ejeren af disse kilder vil slette dem fra hans/hendes domæne, og de vil forsvinde fra din dokumentation: !(url grafiki)
Eksempel: I min README-fil, som jeg ønsker at sætte en blok skema, der ville illustrere, hvordan en algoritme fungerer., Jeg holder mit skema.jpg-fil i en mappe kaldet billeder. For at vise det i min dokumentation bruger jeg en kode:
!(./images/schema.jpg)omfang af funktionaliteter
Der er ikke altid brug for at beskrive omfanget af funktionaliteter. For en hjemmeside-visitkort eller en simpel anvendelse af to-do type, listen over funktionaliteter er et overskud af formular.,
På den anden side kan et tilsyneladende simpelt projekt som opgaveliste udvides med mange interessante muligheder, vi kan være stolte af: brugere registrerer, optager og klassificerer opgaverne efter dato, tilføjer kommentarer til opgaverne eller Dataeksport til filerne.
eksempler på brug
i tilfælde af genanvendelig kode eller dit eget bibliotek kan det være nødvendigt at give en manual til, hvordan du bruger vores projekt., Det kan virke som et fragment af kode:
## Code ExamplesTo generate lorem ipsum use special shortcode: `put-your-code-here`der vil blive vist som:
projektets status
Det er værd at tilføje et projekt status – især hvis projektet er stadig under udvikling. Hvis det er vores bibliotek, lad os nævne planlagte ændringer, udviklingsretning eller for at understrege, at vi er færdige med dens udvikling.
kilder
skal vi tilføje oplysninger, når vores projekt var baseret på en tutorial, eller vi blev inspireret af en given opgave? Ja, selvfølgelig.
Jeg får ikke tvivl i den sag., Der er intet pinligt i det faktum, at vi lærer fra forskellige kilder, og vi dokumenterer vores fremskridt. Vi gennemfører mange tutorials, vælger læringsmateriale. En tankeløs kopiering uden at give ændringer i det – og uden at lære overhovedet – sker for det meste ikke.
Hvis vores kode var baseret på en andens kode, bør vi tilføje sådanne oplysninger.
måske bruger vi en gammel tutorial – for eksempel skriver vi en ansøgning med Rails 3 tutorial. Fra bunden, i overensstemmelse med Rails 5 version, ved hjælp af nye rammemekanismer. Det er bestemt værd at nævne her.,
Når vores kodeks kun var inspireret af en anden løsning/et program, kan du nævne det, og skriv den måde, du blev inspireret, hvilke ændringer du har lavet, hvilke funktionaliteter der blev udviklet.
Når vi løser sæt øvelser, er det værd at tilføje, hvor andre kan finde deres beskrivelse. Hvis vi ønsker at vende tilbage til disse kilder, kommer linket let op. På denne måde er forfatteren, der delte sin viden, brugt sin tid til at forberede og dele dette materiale, også respekteret.,
Andre oplysninger
Oplysninger om forfatteren, kontakt, www og sociale medier links, en type licens i henhold til, hvor koden er gjort tilgængelig, eller oplysninger om, hvordan til at bidrage til et projekt – disse er kun eksempler på hvad der kan være tilføjet til dit projekt.
en god, læselig README
ovenstående forslag er mine. Det vigtigste punkt er bare læsbarhed. En grundig dokumentation gøre din repository skinne foran personalekonsulenter og andre programmører. Der er mange tilgange til at skrive en god README., Se på følgende eksempler:
- Node-chat – En simpel beskrivelse, skærmbillede af applikationen, eksempler på brug
- Weebapp – et glimrende eksempel på beskrivelse, der leveres til en destinationsside type websiteebsted og applikation ved hjælp af API. Beskrivelse hvordan det fungerer, skærmbilleder, teknologier anvendt i denne løsning, yderligere oplysninger om funktionaliteter, der vil blive implementeret
- Pomolectron – vi har et logo, skærmbillederne, en instruktion om installation og en beskrivelse af, hvordan det fungerer
- Git point – eksemplarisk Android-applikation., En indholdsfortegnelse gør navigationen lettere, skærmbillederne, de nævnte funktionaliteter og oplysninger om, hvordan man understøtter applikationens udvikling
README-skabelon
Jeg efterlader dig her et eksempel på README.md fil skabelon, du kan do .nloade. Tag et kig på dens formatering, og kopier en RA, – version til din README.md fil.
artiklen er også tilgængelig på polsk den Flynerd.pl blog.