By Marcin Dubel, Appilon

Schone R-code is van cruciaal belang

 
 
Door mijn jarenlange ervaring met het leveren van succesvolle projecten heb ik één gemeenschappelijk element in elke implementatie ontdekt. Een schone, leesbare en beknopte codebase is de sleutel tot effectieve samenwerking en biedt de klant de hoogste kwaliteitswaarde.

Codebeoordeling is een cruciaal onderdeel van het handhaven van een codeproces van hoge kwaliteit. Het is ook een geweldige manier om best practices te delen en kennis onder teamleden te verspreiden. Bij Appsilon beschouwen we code review als een must voor elk project. Lees meer over hoe wij ons werk organiseren Olga's blogpost over best practices die worden aanbevolen voor alle data science-teams.

Het hebben van een goed ontwikkeld codebeoordelingsproces verandert niets aan het feit dat de ontwikkelaar verantwoordelijk is voor het schrijven van goede, schone code! Het aanwijzen van alle fundamentele fouten in de code is pijnlijk, tijdrovend en leidt reviewers af van het diep ingaan op de codelogica of het verbeteren van de effectiviteit van de code.

Slecht geschreven code kan ook het moreel van het team schaden – coderecensenten zijn gefrustreerd, terwijl codemakers zich misschien beledigd voelen door een groot aantal opmerkingen. Daarom moeten ontwikkelaars ervoor zorgen dat de code zo schoon mogelijk is voordat ze de code ter beoordeling verzenden. Houd er ook rekening mee dat er niet altijd een coderecensent is die te hulp kan komen. Soms sta je er alleen voor in een project. Ook al denk je dat de code nu goed voor je is, overweeg dan om hem over een paar maanden opnieuw te lezen. Je wilt dat het duidelijk is om te voorkomen dat je later je eigen tijd verspilt.

In dit artikel vat ik de meest voorkomende fouten samen die je kunt vermijden en geef ik een overzicht van best practices die je bij het programmeren in het algemeen moet volgen. Volg deze tips om het iteratieproces van de codebeoordeling te versnellen en een rockstar-ontwikkelaar te zijn in de ogen van uw recensent!

Vermijd opmerkingen met opmerkingen

 
 
Het toevoegen van commentaar aan de code is een cruciale vaardigheid voor ontwikkelaars. Een belangrijkere en moeilijker te beheersen vaardigheid is echter weten wanneer niet om commentaar toe te voegen. Goede commentaren schrijven is meer een kunst dan een wetenschap. Er is veel ervaring voor nodig, en je kunt er hele hoofdstukken in een boek over schrijven (bijv. hier). 

Er zijn een paar eenvoudige regels die u moet volgen om opmerkingen over uw opmerkingen te vermijden:

• De commentaren moeten externe kennis aan de lezer toevoegen: als ze uitleggen wat er in de code zelf gebeurt, is dit een alarmsignaal dat de code niet schoon is en moet worden aangepast. Als er een hack is gebruikt, kunnen opmerkingen worden gebruikt om uit te leggen wat er aan de hand is. Commentaar vereist bedrijfslogica of uitzonderingen zijn met opzet toegevoegd. Probeer te bedenken wat verrassend kan zijn voor de toekomstige lezer en voorkom hun verwarring.
• Schrijf alleen cruciale opmerkingen! Uw opmerkingen mogen geen woordenboek zijn met gemakkelijk doorzoekbare informatie. Over het algemeen leiden opmerkingen af ​​en leggen ze de logica niet zo goed uit als de code. Onlangs zag ik bijvoorbeeld onlangs een opmerking als deze in de code: trimws(.) # this function trims leading/trailing white spaces – wat overbodig is. Als de lezer niet weet welke functie trimws doet, kan dit eenvoudig worden gecontroleerd. Een krachtiger commentaar kan hier nuttig zijn, bijvoorbeeld: trimws(.) # TODO(Marcin Dubel): Trimming white spaces is crucial here due to database entries inconsistency; data needs to be cleaned.
• Bij het schrijven van functies in R raad ik aan met behulp van {roxygen2} opmerkingen zelfs als u geen pakket schrijft. Het is een uitstekend hulpmiddel voor het organiseren van de kennis over het functiedoel, de parameters en de output.
• Schrijf commentaar (en alle delen van de code) alleen in het Engels. Door het voor alle lezers begrijpelijk te maken, kunt u coderingsproblemen besparen die kunnen optreden als u speciale tekens uit uw moedertaal gebruikt.
• In het geval dat bepaalde code in de toekomst opnieuw moet worden bewerkt/gewijzigd, markeer deze dan met de # TODO opmerking. Voeg ook wat informatie toe om u te identificeren als de auteur van deze opmerking (waarmee u contact kunt opnemen als er details nodig zijn) en een korte uitleg waarom de volgende code is gemarkeerd als TODO en niet meteen is gewijzigd.
• Laat commentaarcode nooit onbecommentarieerd achter! Het is prima om sommige onderdelen voor de toekomst te bewaren of ze een tijdje uit te schakelen, maar markeer altijd de reden voor deze actie.

Houd er rekening mee dat de opmerkingen in de code blijven staan. Als u iets aan uw recensent wilt vertellen, maar slechts één keer, voeg dan een opmerking toe aan Pull (Merge) Request en niet aan de code zelf.

Voorbeeld: Ik zag onlangs een deel van de code verwijderen met een opmerking als: "Verwijderd omdat de logica veranderde." Oké, goed om te weten, maar later ziet die opmerking in de code er vreemd uit en is overbodig, omdat de lezer de verwijderde code niet meer ziet.

Strings

 
 
Een veelvoorkomend probleem met betrekking tot teksten is de leesbaarheid van aaneenschakelingen van tekenreeksen. Wat ik veel tegenkom is een overmatig gebruik van de paste functie. Begrijp me niet verkeerd; het is een geweldige functie als je string eenvoudig is, bijv paste("My name is", my_name), maar voor ingewikkeldere vormen is het moeilijk te lezen: 

paste("My name is", my_name, "and I live in", my_city, "developing in", language, "for over", years_of_coding)

Een betere oplossing is om te gebruiken sprintf functies of glue, bijv 

glue(“My name is {my_name} and I live in {my_city} developing in {language} for over {years_of_coding}”)

Is het niet duidelijker zonder al die komma's en aanhalingstekens?

Als je met veel codeblokken te maken hebt, zou het geweldig zijn om ze naar aparte locaties te extraheren, bijvoorbeeld naar een .yml-bestand. Het maakt zowel code- als tekstblokken gemakkelijker te lezen en te onderhouden.

De laatste tip met betrekking tot teksten: een van de debugging-technieken die vaak in Shiny-applicaties wordt gebruikt, is het toevoegen print() verklaringen. Controleer nogmaals of de afdrukken niet in de code zijn achtergebleven – dit kan behoorlijk gênant zijn tijdens het beoordelen van de code!

Passanten

 
 
Loops zijn een van de programmeerbouwstenen en zijn een zeer krachtig hulpmiddel. Niettemin kunnen ze rekenintensief zijn en moeten ze daarom zorgvuldig worden gebruikt. De vuistregel die u moet volgen is: controleer altijd of looping een goede optie is. Het is nauwelijks een geval dat u rijen moet doorlussen data.frame: er moet een zijn {dplyr} functie om het probleem efficiënter aan te pakken. 

Een andere veel voorkomende bron van problemen is het herhalen van elementen met behulp van de lengte van het object, bijvoorbeeld for(i in 1:length(x)) .... Maar wat als de lengte van x nul is! Ja, de lus gaat een andere kant op voor iteratorwaarden 1, 0. Dat is waarschijnlijk niet jouw plan. Gebruik makend van seq_along or seq_len functies zijn veel veiliger.

Denk ook aan de apply familie van functies voor looping. Ze zijn geweldig (en niet te vergeten {purrr} oplossingen)! Houd er rekening mee dat het gebruik van sapply kan door de recensent worden opgemerkt als niet stabiel – omdat deze functie zelf het type uitvoer kiest! Dus soms zal het een lijst zijn, soms een vector. Gebruik makend van vapply is veiliger, omdat de programmeur de verwachte uitvoerklasse definieert.

Code delen

 
 
Zelfs als u alleen werkt, wilt u waarschijnlijk graag dat uw programma correct werkt op andere machines. En hoe cruciaal is het wanneer u de code met het team deelt! Om dit te bereiken, mag u nooit absolute paden in uw code gebruiken, bijvoorbeeld “/home/marcin/my_files/old_projects/september/project_name/file.txt”. Voor anderen zal het niet toegankelijk zijn. Houd er rekening mee dat elke overtreding van de mapstructuur de code zal laten crashen. 

Omdat u voor al het codeerwerk al een project zou moeten hebben, moet u paden gebruiken die verband houden met het specifieke project – in dit geval; het zal “./bestand.txt” zijn. Bovendien zou ik willen voorstellen om alle paden als variabelen op één plek te bewaren – zodat het hernoemen van een bestand één verandering in de code vereist, en niet bijvoorbeeld twintig in zes verschillende bestanden.

Soms moet uw software bepaalde inloggegevens of tokens gebruiken, bijvoorbeeld voor een database of privéopslagplaatsen. U mag dergelijke geheimen nooit in de repository plaatsen! Zelfs als de inzendingen binnen het team hetzelfde zijn. Meestal is het een goede gewoonte om dergelijke waarden binnen de perken te houden .Renviron bestand als omgevingsvariabelen die bij het opstarten worden geladen en het bestand zelf wordt in de repository genegeerd. Je kunt er meer over lezen hier.

Goede programmeerpraktijken

 
 
Laten we ons ten slotte concentreren op hoe u uw code kunt verbeteren. Allereerst moet uw code gemakkelijk te begrijpen en schoon zijn. Zelfs als u alleen werkt, zal het uw leven gemakkelijker maken als u na een tijdje weer gaat coderen! 

Gebruik specifieke namen van variabelen, zelfs als ze lang lijken. De vuistregel is dat je moet kunnen raden wat er in zit, alleen al door de naam te lezen. table_cases_per_country is ok, maar tbl1 is niet. Vermijd afkortingen. Langdurig verdient de voorkeur boven vaag. Houd een consistente stijl aan voor objectnamen (zoals camelCase of snake_case) waarover de teamleden overeenstemming hebben bereikt. 

Kort logische waarden NIET af T For TRUE en F For FALSE – de code zal werken, maar T en F zijn reguliere objecten die tijdens het schrijven kunnen worden overschreven TRUE en FALSE zijn bijzondere waarden. 

Vergelijk geen logische waarden met behulp van vergelijkingen, zoals if(my_logical == TRUE). Als je ermee kunt vergelijken TRUE, betekent dit dat uw waarde al logisch is, dus if(my_logical) is genoeg! Als u nogmaals wilt controleren of de waarde is TRUE inderdaad (en niet bijv. NA), kunt u de isTRUE() functie.

Zorg ervoor dat uw logische uitspraken correct zijn. Controleer of je het verschil in R tussen begrijpt enkele en dubbele logische operatoren!

Een goede spatiëring is cruciaal voor de leesbaarheid. Zorg ervoor dat de regels hetzelfde zijn en afgesproken zijn in het team. Het maakt het gemakkelijker om elkaars code te volgen. De eenvoudigste oplossing is om op de schouders van reuzen te gaan staan ​​en de volgelingen te volgen Opgeruimde stijlgids. 

Het controleren van de stijl in elke regel tijdens de beoordeling is echter behoorlijk inefficiënt, dus zorg ervoor dat u deze introduceert linter en styler in uw ontwikkelingsworkflow, zoals gepresenteerd in Olga's blogpost. Dit kan levensreddend zijn! Onlangs hebben we een fout gevonden in een verouderde code die automatisch door linter zou zijn herkend:

sum_of_values <- first_element + second_element

Dit levert niet de som van de elementen op zoals de auteur had verwacht.

Over namen van variabelen gesproken: dit staat bekend als een van de moeilijkste dingen bij het programmeren. Vermijd het dus als het niet nodig is. Houd er rekening mee dat R-functies standaard het laatst gemaakte element retourneren, zodat u dat eenvoudig kunt vervangen:

sum_elements <- function(first, second) { my_redundant_variable_name <- sum(first, second) return(my_redundant_variable_name)
}

Met iets korters (en eenvoudiger, je hoeft niet aan namen te denken):

sum_elements <- function(first, second) { sum(first, second)
}

Aan de andere kant, gebruik alstublieft WEL extra variabelen wanneer u een functieaanroep of berekening herhaalt! Het zal het computationeel effectiever maken en in de toekomst gemakkelijker kunnen worden aangepast. Vergeet niet uw code te bewaren DROOG – herhaal jezelf niet. Als u code kopieert en plakt, denk dan twee keer na of deze niet in een variabele moet worden opgeslagen, in een lus moet worden uitgevoerd of naar een functie moet worden verplaatst. 

Conclusie

 
 
En daar heb je het: vijf strategieën om schone R-code te schrijven en je code-recensent commentaarloos te laten. Deze vijf alleen al zorgen ervoor dat u code van hoge kwaliteit schrijft die gemakkelijk te begrijpen is, zelfs jaren later. Veel codeerplezier!

 
Bio: Marcin Dubel is ingenieur bij Appsilon.

ORIGINELE. Met toestemming opnieuw gepost.

Zie ook:

• Ondersteuning van vectormachine voor handgeschreven alfabetherkenning in R.
• De beste programmeertalen en hun gebruik
• Een gids over hoe u een datawetenschapper kunt worden (stapsgewijze aanpak)