sdj_raising_your_code_to_professional_standards
1.0.0
Dies ist die grobe Version des Artikels, das bei sdjournal unter https://sdjournal.org/raising-code-professional-standardards veröffentlicht wurde. Mein Artikel befindet sich im kostenlosen Abschnitt und Sie können sich mit einem Github -Konto anmelden.
Du willst gut sein. Sie möchten lernen, ein Paket zu schreiben, das allen Expertenrichtlinien folgt. Sie sind offen für ein professionelles Werkzeug und lernen daraus. Sie möchten wie die Profis programmieren. Sie möchten ein Paket erstellen, auf das Sie stolz sind.
Dann sollten Sie diesen Artikel lesen.
Sie lernen, automatische Tests zur Codierung von Standard- und Codeabdeckungen und guten Praktiken hinzuzufügen. Dies alles wird durch einen Git -Push den Befehl ausgelöst, der den Code Ihres Pakets in seinen GitHub hochlädt.
Wir werden ein Beispielpaket als Testfall verwenden.
Am Ende haben Sie ein Skript, das Sie dazu zwingt, wie ein Profi zu arbeiten.
Es wird angenommen, dass Sie wissen, wie es geht
Falls Sie noch keine R -Funktion lesen können, empfehle ich, [Matloff, 2011] zu lesen oder das Paket "Wirbel" zu verwenden.
Falls Sie kein Paket schreiben, testhat verwenden oder GitHub kennen, empfehle ich, [Hadley, 2015] zu lesen.
Ich genieße es, Programmierung nach den höchsten Standards der Branche zu unterrichten. Meine Schüler im Alter von 7 bis 77 Jahren sind alle mit Beratungszitaten aus der Literatur konfrontiert, insbesondere aus dem 'Pragmatischen Programmierer' von Andrew Hunt und David Thomas. In Bezug auf R zitiere ich gerne alle Ratschläge von Hadley Wickham.
Nach den guten Praktiken der Experten sparen Sie Zeit bei der Entwicklung von Code.
Die Einrichtung dieses Artikels folgt einigen dieser guten Praktiken. Die Praktiken sind ein rationaler Codierungsstandard, haben eine hohe Codeabdeckung (alle Code wird getestet) und verwenden R auf pragmatische Weise.
In diesem Artikel werde ich zeigen, wie man von den Experten unterstützt wird.
Zunächst werde ich das Paket 'prde' vorstellen ('Professional R Development Beispiel'). Dieses Paket dient als Testfall dafür, wie seine Fehler durch das Setup dieses Artikels ausgesetzt sind. Das Paket ist somit absichtlich fehlerhaft und besteht jedoch alle Kranentests. 'PRDR' wird auf GitHub gehostet.
Dann zeige ich, wie Sie Konten für zwei Websites einrichten, die nahtlos mit einem GitHub -Konto interagieren. Dies sind Travis CI, um automatische Tests (dazu später mehr) und Codecov einzurichten, die die Berichterstattung des Paketcodes verfolgt (dazu später mehr).
Wenn alle Websites aktiviert werden, wird eine Datei auf den GitHub des Pakets hochgeladen, wodurch die Antworten von der Website von Travis CI und Codecov ausgelöst werden. Ich werde diese Antworten einzeln besprechen.
Der Testfall ist ein Paket namens "Prde", das der in [Wickham, 2015] beschriebenen Struktur folgt. Das Paket wird auf GitHub gehostet:
Abbildung 1. Der GitHub des Pakets 'Prde'
Innerhalb des Pakets "PRDE" befindet sich eine Funktion, die do_magic so genannt wird:
#' Multiplies all values by two,
#' except 42, which stays 42
#' @param x input, must be numeric
#' @return magicified output
#' @export
do_magic <- function(x)
{
if (!is.numeric(x)) {
stop("x must be numeric");
}
out = x * 2;
out = replace(out, out == 84, 42);
out;
}
Auflistung 1. Die Funktion 'do_magic'
Die Funktion do_magic wird in einer Datei an einem herkömmlichen Ort gespeichert, das r/do_magic.r ist. Es wird mit dem Paket "Roxygen2" dokumentiert. Die Funktion überprüft die korrekte Eingabe und fällt schnell fehl, wenn sie diese nicht verarbeiten kann.
Das Paket enthält einige Tests unter Verwendung von "testhat", wie unten gezeigt:
context("do_magic")
test_that("do_magic: use", {
expect_equal(do_magic(42), 42)
expect_equal(do_magic(1), 2)
})
Auflistung 2. Die Do_Magic -Tests
Dieser Test wird in einer Datei an einem herkömmlichen Ort gespeichert, das Tests/testthat/test-do_magic.r ist. Die Tests bestehen alle. Es werden keine Fehler gefunden, wenn das Paket überprüft wird, um in RSTUDIO zu erstellen oder Devtools :: check () . Das heißt, das Paket kann ohne Probleme an Cran gesendet werden (außer dass das Paket relevant ist)!
Durch kontinuierliche Integration wird der Effekt von geänderten Code nach dem Hochladen auf GitHub nach kurzer Zeit automatisch angezeigt. Mit anderen Worten: Wenn das Paket nicht mehr durch einen eingeführten Fehler erstellen kann (beispielsweise ein Test, der jetzt fehlschlägt), wird es frühzeitig bemerkt. Oder, wenn jemand anderes es bricht, wird das Team früh bemerken. Wenn jemand eine Pull -Anfrage einreicht, kann er sehen, ob er das Erstellen des Pakets brechen wird, bevor er es akzeptiert.
Es gibt viele andere kontinuierliche Integrationsdienste, die genauso gut funktionieren, wie Jenkins, Codeship, Circleci und Wercker. Ich habe gerade zuerst Travis CI gelernt.
Abbildung 2. Das Travis CI -Logo
Der erste Schritt unseres Setups besteht darin, Travis CI zu aktivieren.
Travis CI ist ein kontinuierlicher Integrationsdienst (daher der CI im Namen), der bei der Entwicklung von Zahnseide -Software frei zu verwenden ist und gut mit GitHub funktioniert.
Lassen Sie uns zuerst Travis CI aktivieren, denn nur dann, wenn es aktiviert wird, wird es auf einem Upload zu GitHub ausgeführt.
Um dies zu tun: Besuchen Sie die Travis CI-Website www.travis-ci.org und melden Sie sich mit einem Github-Konto an. Travis fordert die Genehmigung für einige GitHub -Informationen wie Benutzername und E -Mail an. Nach der Genehmigung zeigt Travis CI alle Github -Repositorys des Benutzers und ihren Aktivierungsstatus:
Abbildung 3. Übersicht über Githubs, die von Travis CI überprüft wurden
In dieser Abbildung wird ein Benutzer angezeigt, der mindestens drei Github -Repositorys hat, von denen man nicht aktiviert ist (das graue Kreuz) und zwei sind (die grüne Prüfung).
Finden Sie den GitHub eines R -Pakets und aktivieren Sie es.
Die Codeabdeckung ist der Prozentsatz der von Tests abgedeckten Codezeilen. Wenn eine Zeile nicht getestet wird, wird entweder der tote Code erkannt (der entfernt werden kann) oder ein Test sollte geschrieben werden, der diesen Code verwendet. Die Codeabdeckung korreliert mit der Codequalität [Del Frate et al., 1995].
Es gibt andere Dienste, die die Codeabdeckung verfolgen, wie Codeklima, Codacity, Coveralls, QuantifiedCode und vieles mehr. Es ist einfach so, dass das Paket, das wir verwenden ('lintr'), Codecov verwendet.
Abbildung 4. Das Codecov -Logo
Der zweite Schritt besteht darin, Codecov zu aktivieren.
CodeCOV ist eine Website, die die Codeabdeckung eines Github-Repositorys in benutzerfreundlicher Form zeigt. Codecov verfolgt die Codeabdeckung eines Projekts im Laufe der Zeit. Wenn es mehrere Git -Zweige gibt, wird für jeden Zweig separat angezeigt.
Wir müssen jetzt Codecov aktivieren, weil
CodeCOV empfängt und zeigt die Codeabdeckung registrierter Benutzer nur.
Um Codecov zu aktivieren, gehen Sie zu seiner Website https://codecov.io und melden Sie sich mit einem Github -Konto an. Es wird die Genehmigung für einige GitHub -Informationen wie Benutzername und E -Mail anfordern.
Nach der Autorisierung zeigt CodeCOV die Codeabdeckung aller Githubs des Benutzers an. Für einen neuen Benutzer ist dieser Bildschirm größtenteils leer, da noch die Abdeckung eines Codes gemessen wurde. Für einen Benutzer, der die Codeabdeckung von mehreren Github -Repositories hat, sieht der CODECOV -Bildschirm so aus:
Abbildung 5: Beispielübersicht über GitHubs, die von Codecov überprüft wurden
In dieser Abbildung kann man einen Verwendungszweck sehen, der mindestens drei Github -Repositorys enthält, bei denen die Codeabdeckung überprüft wird.
Der dritte Schritt besteht darin, Travis CI zu unterweisen, was zu tun ist, wenn neuer Code in einen aktivierten GitHub hochgeladen wird.
Travis wird angewiesen, was mit einem Build -Skript zu tun ist, bei dem es sich um eine Klartextdatei namens .Travis.yml handelt. Der Dateiname beginnt mit einem Punkt, wodurch er zu einer versteckten Datei auf UNIX -Systemen wird. Die Erweiterung von '.yml' ist eine Abkürzung von "Eine weitere Markup -Sprache". Travis CI wird in der Bash -Befehlssprache angewiesen.
Erstellen Sie im Stammordner des Projekts eine Datei namens .travis.yml und geben Sie den folgenden Text hinein:
language: r
cache: packages
r_github_packages:
- jimhester/lintr
- jimhester/covr
- MangoTheCat/goodpractice
after_success:
- Rscript -e "lintr::lint_package()"
- Rscript -e "covr::codecov()"
- Rscript -e "goodpractice::gp()"
Listing 3. Das Travis CI -Skript
Dies ist ein einfaches und unkompliziertes .travis.yml -Skript. In der ersten Zeile heißt es, dass die hier verwendete Programmiersprache R. Die zweite Zeile gibt Travis CI an, die installierten Pakete in einem Cache zu halten, um unnötige Neustände dieser Pakete zu verhindern. Der Abschnitt 'r_github_packages' weist Travis CI an, diese mit Github veranstalteten Pakete zu installieren. Der Abschnitt "After_Success" wird ausgeführt, nachdem das Paket ein devtools :: check () übergeht. In diesem Abschnitt werden Schecks aus den Paketen "Lintr", "Covr" und "GoodPractice" ausgeführt. Mehr zu diesen Paketen später.
Laden Sie nach der Erstellung dieser .Travis.yml -Datei sie in GitHub hoch.
Nach dem Hochladen von .travis.yml in einen GitHub wird es sofort auf Github sichtbar sein:
Abbildung 6. Der "Prde" -Github nach dem Hinzufügen des Travis CI Build -Skripts
Dieser Druck zu einem Github löst Travis CI aus und wird sofort damit beginnen, seine Arbeit zu erledigen.
Travis CI braucht einige Zeit, um eine virtuelle Maschine einzurichten. Jedes Mal, wenn ein Upload in GitHub hergestellt wird, wird eine virtuelle Maschine erstellt, um eine reproduzierbare Build- und Testumgebung zu gewährleisten.
Um zu sehen, dass Travis CI seine Arbeit erledigt, kehren Sie auf die Travis CI-Website https://travis-ci.org zurück. Nach ungefähr einer Minute wird der Fortschritt von Travis CI sichtbar. Travis CI installiert zunächst alle Pakete und ihre Abhängigkeiten. Das .Travis.yml -Skript zwischenstrichen alle Pakete und macht den zweiten Build schneller.
Hier ist der Header des "Prde" -Pakets sein erstes Build:
Abbildung 7. Header des PRDE -Pakets sein erstes Build
Wir wissen bereits, dass das Paket diesen Scheck bestehen wird, da dies bereits in RStudio überprüft wurde. Sollte der Build nicht passieren, wird die gleiche Ausgabe von Devtools :: check () und nichts weiter angegeben. Wenn der Build verabschiedet wird, gibt es unten einige neue Informationen:
Abbildung 8. unten im Paket "PRDE" sein erstes Build
Wenn Sie auf die Dreiecke links klicken, werden einige zusätzliche Informationen angezeigt.
Zunächst erweitern wir das Feedback aus dem "Lintr" -Paket (von Jim Hester). Es zeigt:
Abbildung 9. Das Feedback, das das "Lintr" -Paket gegeben hat
'lintr' ist ein Paket, um zu überprüfen, ob das Paket seines Codierungsstils gut angestellten Standards entspricht, wie die von Wickham (2014) und Wickham (2015).
Abbildung 10. Jim Hester
Die Ausgabe von 'Lintr' wird nicht nur auf der Travis CI -Website angezeigt. Auch mein guter Freund Lintr-Bot kommentiert den Commit to GitHub mit genau den gleichen Nachrichten:
Abbildung 11. Kommentare von Lintr-BOT im Commit, wie in GitHub gezeigt
Lintr-Bot ist immer richtig. Bei Bedarf kann 'Lintr' hergestellt werden, um andere Codierungsstandards zu ermöglichen.
Abbildung 12. Das Mangothecat -Logo
Wenn wir uns von LINTR-BOTS-Wörtern der Weisheit weitergeben, werden wir das Feedback aus dem Paket "GoodPractice" (von Mangothecat) erweitern. Dieser zeigt:
Abbildung 13. Feedback durch das "GoodPractice" -Paket
'GoodPractice' erweitert 'lintr' durch Hinzufügen guter Praktiken. Zum Beispiel kann es vorschlagen, eine bestimmte Funktion nicht zu verwenden, sondern stattdessen eine bessere Alternative zu verwenden.
Es gibt ein drittes Dreieck, das erweitert werden kann und Informationen zum Aufruf des COVR -Pakets im Travis Build -Protokoll liefert. Das Anzeigen dieser Informationen hier ist nicht hilfreich, da sie in groben Form angezeigt wird. Kehren Sie stattdessen zur Codecov -Website https://codecov.io zurück, um die Codeabdeckung auf schönere Weise anzuzeigen:
Abbildung 14. Feedback durch das "CoVR" -Paket, wie von Codecov angezeigt
Die Codeabdeckung zeigt, dass der Autor des Pakets des Pakers des Pakers vergessen hat, zu testen, ob die do_magische Funktion tatsächlich eine Ausnahme ausgelöst hat, wenn die Eingabe nicht numerisch ist.
Dank diesen ist es die Tools (und die Leute, die diese geschrieben haben) einfacher, ein besserer R -Programmierer zu werden.
Ich schlage vor, diese Ratschläge anzuhören und diesen zu folgen.
Wenn man den Rat der Experten nicht einverstanden ist, bin ich immer gespannt, warum. Die Experten haben diese Standards aus einem bestimmten Grund ausgewählt. Und diese Experten sind sich auch der Argumente bewusst, die andere Standards begünstigen.
Für meine Schüler erzwinge ich ein sauberes "Oclint" und "GoodPractice" -Protokoll und eine Codeabdeckung von mindestens 95%.
Diese Techniken können von jedem von Anfang bis hin zu erfahrenen Programmierern eingesetzt werden. Für die Entwicklung der Zahnseide sind Github, Travis CI und Codecov kostenlos, während die Entwicklung geschlossener Source eine Gebühr darstellt.
Code better. Sleep better. [Langr, 2013]
Wenn alle Tests gelöscht werden und die Code -Abdeckung mit hoher Code abgebildet sind, kann dies der Welt angezeigt werden. Dies kann durch Hinzufügen von Build -Abzeichen zur lesMe.md -Datei im Hauptordner des Github hinzugefügt werden. Solche Abzeichen sehen so aus:
Abbildung 15. Die auf dem "PRDE" -Github angezeigten Abzeichen
Um diese Abzeichen anzuzeigen, fügen Sie den folgenden Code dem Hauptordner eines Github -Ordners zum Readme.md hinzu:
[](https://travis-ci.org/[yourname]/[package name])
[](https://codecov.io/github/[yourname]/[package name]?branch=master)
Auflistung 4. Statusabzeichen anzeigen
Ich hoffe, es wird andere Menschen dazu inspirieren, dasselbe zu tun. Es tat es für mich.
In diesem Artikel haben Sie gelernt, sich zu korrigieren, wenn Sie von der guten Praxis der Experten abweichen.
Wir haben zwei Website -Konten erstellt und aktiviert und eine Textdatei geschrieben. Die Zeit, in der wir diese Tools eingerichtet haben, wird von den zukünftigen Änderungen in unserem R -Paket zurückgewonnen.
Ich möchte Luis Boullosa, Rampal S. Etienne und Cyrus A. Mallon für ihr Feedback zu früheren Entwürfen dieses Artikels danken.
git push : Der Befehl GIT, den geänderten Code in einen Git -Repository -Host hochzuladen
