sdj_raising_your_code_to_professional_standards
1.0.0
Ceci est la version approximative de l'article publié à sdjournal , à https://sdjournal.org/railing-code-professional-standards. Mon article est dans la section gratuite et vous pouvez vous inscrire avec un compte GitHub.
Vous voulez être bon. Vous souhaitez apprendre à rédiger un package qui suit toutes les directives d'experts. Vous êtes ouvert à être corrigé par n'importe quel outil professionnel et à en apprendre. Vous voulez programmer comme les pros. Vous souhaitez créer un package dont vous êtes fier.
Ensuite, vous devriez lire cet article.
Vous apprendrez à ajouter des tests automatiques pour la couverture des normes et du code de codage et de bonnes pratiques. Tout cela est déclenché par un git pousse la commande qui télécharge le code de votre package sur son github.
Nous utiliserons un exemple de package comme cas de test.
En fin de compte, vous aurez un script qui vous oblige à travailler comme un pro.
On suppose que vous savez comment
Si vous n'êtes pas encore en mesure de lire une fonction R, je recommande de lire [Matloff, 2011] ou d'utiliser le package «Swirl».
Dans le cas où vous n'êtes pas en mesure d'écrire un package, d'utiliser TestThat ou Know Github, je recommande de lire [Hadley, 2015].
J'aime enseigner la programmation en suivant les normes les plus élevées de l'industrie. Mes étudiants, âgés de 7 à 77 ans, sont tous confrontés à des citations de conseils de la littérature, en particulier du «programmeur pragmatique» par Andrew Hunt et David Thomas. En ce qui concerne R, j'aime citer tous les conseils de Hadley Wickham.
Suivre les bonnes pratiques des experts gagnera du temps dans le développement du code.
La configuration de cet article suit certaines de ces bonnes pratiques. Les pratiques sont une norme de codage rationnelle, ont une couverture de code élevée (tout le code est testé) et utilise R de manière pragmatique.
Dans cet article, je vais montrer comment être aidé par les experts.
Tout d'abord, je présenterai le package «PRDE» («Exemple de développement professionnel»). Ce package sert de cas de test pour montrer comment ses défauts sont exposés par la configuration de cet article. L'ensemble est donc défectueux exprès, mais passe tous les tests CRAN. «Prdr» est hébergé sur GitHub.
Ensuite, je montre comment configurer des comptes pour deux sites Web qui interagiront parfaitement avec un compte GitHub. Ce sont Travis CI, pour la configuration des tests automatiques (plus à ce sujet plus tard), et Codecov qui suit la couverture du code du package (plus à ce sujet plus tard).
Ayant tous les sites Web activés, un fichier est téléchargé sur le GitHub du package, qui déclenchera les réponses par le site Web Travis CI et Codecov. Je vais discuter de ces réponses un par un.
Le cas de test est un package appelé «prde», qui suit la structure décrite dans [Wickham, 2015]. Le package est hébergé sur github:
Figure 1. Le github du package «prde»
Dans le package 'Prde' réside une fonction, appelée DO_MAGIC , comme ceci:
#' 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;
}
Listing 1. La fonction «do_magic»
La fonction DO_MAGIC est stockée dans un fichier à un emplacement conventionnel, qui est r / do_magic.r . Il est documenté à l'aide du package «Roxygen2». La fonction vérifie les entrées correctes et échoue rapidement s'il ne peut pas les traiter.
Le package a des tests, en utilisant «TestThat», comme indiqué ci-dessous:
context("do_magic")
test_that("do_magic: use", {
expect_equal(do_magic(42), 42)
expect_equal(do_magic(1), 2)
})
Listing 2. Les tests DO_MAGIC
Ce test est stocké dans un fichier à un emplacement conventionnel, qui est des tests / testshat / test-do_magic.r . Les tests passent tous. Aucune erreur n'est trouvée lorsque le package est vérifié pour construire dans rstudio ou utiliser Devtools :: Check () . Cela signifie que le colis peut être envoyé à Cran sans aucun problème (sauf pour convaincre que le colis est pertinent)!
L'intégration continue signifie que l'effet du code modifié, après l'avoir téléchargé sur github, est affiché automatiquement après un court laps de temps. En d'autres termes: si le package ne peut plus construire par un défaut introduit (par exemple, un test qui échoue maintenant), il sera remarqué tôt. Ou, si quelqu'un d'autre le brise, l'équipe le remarquera tôt. De plus, lorsque quelqu'un soumet une demande de traction, on peut voir si elle cassera la construction du package avant de l'accepter.
Il existe de nombreux autres services d'intégration continue qui fonctionnent aussi bien, comme Jenkins, Codeship, Circleci et Wercker. Je viens d'apprendre Travis CI en premier.
Figure 2. Le logo Travis CI
La première étape de notre configuration consiste à activer Travis CI.
Travis CI est un service d'intégration continue (d'où le «CI» dans le nom) qui est libre à utiliser lors du développement de logiciels dentaire et fonctionne bien avec GitHub.
Activons d'abord Travis CI, car ce n'est que lorsqu'il est activé, il commencera à fonctionner sur un téléchargement sur github.
Pour ce faire: allez sur le site Web de Travis CI, www.travis-ci.org , et connectez-vous avec un compte GitHub. Travis demande l'autorisation de certaines informations GitHub, comme le nom d'utilisateur et le courrier électronique. Après l'autorisation, Travis CI montre tous les référentiels GitHub de l'utilisateur et leur statut d'activation:
Figure 3. Présentation des githubs vérifiés par Travis CI
Dans cette figure, un utilisateur est montré qui a au moins trois référentiels GitHub, dont on n'est pas activé (la croix grise) et deux sont (la vérification verte).
Allez trouver le github d'un package R et activez-le.
La couverture du code est le pourcentage de lignes de code couvertes par les tests. Si une ligne n'est pas testée, le code mort est détecté (qui peut être supprimé) ou un test doit être écrit qui utilise ce code. La couverture du code est en corrélation avec la qualité du code [Del Frate et al., 1995].
Il existe d'autres services qui suivent la couverture du code, comme le climat de code, la codacity, les couvertures, le code quantifié et bien d'autres. Il se trouve que le package que nous utiliserons ('lintr') utilise Codecov.
Figure 4. Le logo Codecov
La deuxième étape consiste à activer CodeCov.
CodeCov est un site Web qui affiche la couverture de code d'un référentiel GitHub dans un formulaire convivial. Codecov suit la couverture du code d'un projet à travers le temps. S'il y a plusieurs branches GIT, la couverture du code s'affiche séparément pour chaque branche.
Nous devons activer Codecov maintenant, car
Codecov ne recevra et affichera que la couverture du code des utilisateurs enregistrés.
Pour activer Codecov, accédez à son site Web, https://codecov.io , et connectez-vous avec un compte GitHub. Il demandera l'autorisation de certaines informations GitHub, comme le nom d'utilisateur et le courrier électronique.
Après l'autorisation, CodeCov affiche la couverture du code de tous les githubs de l'utilisateur. Pour un nouvel utilisateur, cet écran sera principalement vide, car aucune couverture de code n'a encore été mesurée. Pour un utilisateur qui a mesuré la couverture de code de plusieurs référentiels GitHub, l'écran Codecov ressemblera à ceci:
Figure 5: Exemple de vue d'ensemble des githubs vérifiés par codecov
Dans cette figure, on peut voir une utilisation qui a au moins trois référentiels GitHub qui font vérifier leur couverture de code.
La troisième étape consiste à instruire Travis CI quoi faire lorsque un nouveau code est téléchargé sur un github activé.
Travis est informé ce qu'il faut faire en utilisant un script de construction, qui est un fichier en texte clair nommé .travis.yml . Le nom de fichier commence par un point, ce qui en fait un fichier caché sur les systèmes UNIX. L'extension «.yml» est une abréviation de «encore une autre langue de balisage». Travis CI est instruit dans le langage de commande bash.
Dans le dossier racine du projet, créez un fichier nommé .travis.yml et placez le texte suivant:
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. Le script Travis CI
Ceci est un script .travis.yml simple et simple. La première ligne indique que le langage de programmation utilisé ici est R. La deuxième ligne indique à Travis CI de conserver les packages installés dans un cache, afin d'éviter les réinstallations inutiles de ces packages. La section 'r_github_packages' demande à Travis CI d'installer ces packages hébergés par GitHub. La section 'After_Success' est exécutée après que le package passe un devtools :: check () . Dans cette section, il exécutera des chèques à partir des packages 'Lintr', 'CoVR' et 'Goodpractice'. Plus sur ces packages plus tard.
Après avoir créé ce fichier .travis.yml , téléchargez-le sur github.
Après avoir téléchargé .travis.yml sur un github, il sera visible immédiatement sur github:
Figure 6. Le github 'prde' après avoir ajouté le script de construction Travis CI
Cette poussée vers un github déclenche Travis CI et il commencera immédiatement à faire son travail.
Travis CI a besoin de temps pour configurer une machine virtuelle. Chaque fois qu'un téléchargement vers GitHub est fabriqué, une machine virtuelle est créée pour assurer un environnement de construction et de test reproductible.
Pour voir Travis CI faire son travail, retournez sur le site Web de Travis CI, https://travis-ci.org . Après environ une minute, les progrès de Travis CI deviennent visibles. Travis CI installe d'abord tous les packages et leurs dépendances. Le script .travis.yml cache tous les packages, ce qui rend la deuxième construction plus rapidement.
Voici l'en-tête du package «prde» sa première construction:
Figure 7. En-tête de l'emballage «prde» sa première construction
Nous savons déjà que le package passera ce chèque, car cela a déjà été vérifié dans RStudio. Si la construction ne passe pas, la même sortie sera affichée que celle donnée par Devtools :: Check () et rien de plus. Si la construction passe, il y aura de nouvelles informations en bas:
Figure 8. En bas du package «prde» sa première construction
Cliquer sur les triangles à gauche révèle quelques informations supplémentaires.
Tout d'abord, nous élargirons les commentaires du package 'Lintr' (par Jim Hester). Il montre:
Figure 9. La rétroaction donnée par le package «Lintr»
«Lintr» est un package pour vérifier si le package son style de codage suit des normes bien accélérées, comme celles de Wickham (2014) et Wickham (2015).
Figure 10. Jim Hester
La sortie de «Lintr» n'est pas seulement indiquée sur le site Web de Travis CI. De plus, mon bon ami Lintr-Bot commentera la validation sur GitHub, avec exactement les mêmes messages:
Figure 11. Commentaires de Lintr-Bot sur le commit, comme indiqué sur GitHub
Lintr-bot a toujours raison. Si nécessaire, «lintr» peut être fait pour permettre d'autres normes de codage.
Figure 12. Le logo Mangothecat
En passant à partir de Lintr-Bots Words of Wisdom, nous élargirons les commentaires du package «Goodpractice» (par Mangothecat). Celui-ci montre:
Figure 13. Rétroaction donnée par le package «Goodpractice»
«Goodpractice» étend «Lintr» en ajoutant de bonnes pratiques. Par exemple, il peut suggérer de ne pas utiliser une fonction particulière mais d'utiliser une meilleure alternative à la place.
Il existe un troisième triangle qui peut être étendu, fournissant des informations sur l'appel au package «Covr», dans le journal de construction Travis. La visualisation de ces informations ici n'est pas utile, car elle est affichée sous une forme brute. Au lieu de cela, retournez sur le site Web de Codecov, https://codecov.io, pour afficher la couverture du code de manière plus jolie:
Figure 14. Rétroaction donnée par le package «CoVR», comme affiché par Codecov
La couverture du code montre que l'auteur du package «PRDE» a oublié de tester si la fonction DO_MAGIC lance en effet une exception lorsque l'entrée n'est pas numérique.
Grâce à ceux-ci, les outils (et les personnes qui les ont écrits) sont plus faciles de devenir un meilleur programmeur R.
Je suggère d'écouter ces conseils et de les suivre.
Si l'on n'est pas d'accord sur les conseils des experts, je suis toujours curieux de savoir pourquoi. Les experts ont choisi ces normes pour une raison. Et ces experts sont également conscients des arguments favorisant d'autres normes.
Pour mes élèves, j'applique un journal propre «Oclint» et «Goodpractice» et une couverture de code d'au moins 95%.
Ces techniques peuvent être utilisées par tout le monde du début aux programmeurs expérimentés. Pour le développement de la soie dentaire, Github, Travis CI et Codecov sont gratuits, tandis que le développement de source fermée sollicite des frais.
Code better. Sleep better. [Langr, 2013]
Lors de la réduction de tous les tests et de la couverture du code élevé, cela peut être montré au monde. Cela peut être fait en ajoutant des badges de construction au fichier readme.md , dans le dossier principal du github. De tels badges ressemblent à ceci:
Figure 15. Les badges affichés sur le github 'prde'
Pour afficher ces badges, ajoutez le code suivant à Readme.md dans le dossier principal d'un github:
[](https://travis-ci.org/[yourname]/[package name])
[](https://codecov.io/github/[yourname]/[package name]?branch=master)
Listing 4. Affichage des badges d'état
J'espère que cela inspirera d'autres personnes à faire de même. Ça l'a fait pour moi.
Dans cet article, vous avez appris à vous laisser corriger lorsque vous économisant les bonnes pratiques des experts.
Nous avons créé et activé deux comptes de site Web et écrit un fichier texte. Le temps qu'il nous a fallu pour configurer ces outils sera gagné par les modifications futures de notre package R.
Je tiens à remercier Luis Boullosa, Rampal S. Etienne et Cyrus A. Mallon pour leurs commentaires sur les versions antérieures de cet article.
git push : la commande git pour télécharger du code modifié sur un hôte de référentiel git
