Expliquez votre code en 60 secondes : d'un extrait collé à une vidéo dessinée à la main
Publié · Mis à jour · Jakub Kuźnicki
Politique de mise à jour : les faits produit, les sources citées et les résultats vérifiés sont revalidés lorsqu’ils changent. Voir la méthodologie de l’auteur.
Le problème avec une description PR en six paragraphes
Pouvez-vous imaginer qu'une méthode d'assistance sur six lignes décide que Google n'indexerait pas quatre de vos pages d'accueil ? La pull request qui l'a corrigé contenait un essai de six paragraphes sur ce qui s'est cassé et pourquoi. En réalité, une personne l’a lu et a vaqué à sa journée.
La partie intéressante de ce bug n’a jamais été l’apparence du code final. C'est l'ordre dans lequel vous devez réfléchir : vous remarquez d'abord qu'il y a deux copies de l'assistant, puis que l'une d'elles traite un chemin vide différemment d'une seule barre oblique, puis que les barres obliques finales sont désactivées, et alors seulement il clique sur la raison pour laquelle l'URL canonique pointe vers une redirection. Un diff montre l'état final, pas le chemin qui y mène. Un stylo écrivant ligne par ligne montre le chemin.
Le code
C'est pourquoi j'ai construit Scribe. Lire du code vaut mieux le regarder et s'interroger pendant une heure, et le regarder être écrit vaut les deux.
La prévisualisation est gratuite. Coller, ajuster, dessiner, rejouer : rien de tout cela ne nécessite un compte, et il n'y a pas de limite à la fréquence à laquelle vous le faites. Un compte est nécessaire uniquement pour télécharger la vidéo terminée. Avec le forfait gratuit, vous bénéficiez de cinq exportations par jour UTC, elles sont réinitialisées à 00h00 UTC et portent un petit filigrane todrawn.com. Premium supprime la limite et le filigrane.
Voici l'assistant à l'origine du problème, dans la forme qu'il avait avant le correctif :
function prefixed(locale: AppLocale, path?: string): string {
if (locale === routing.defaultLocale) {
return path || "/";
}
return `/${locale}${path || ""}`;
}Collez-le dans le champ de texte sur Scribe et appuyez sur play. Six lignes, et tout le bug réside dans la différence entre les deux instructions return.
Ajustement
Scribe doit s'adapter à plusieurs flux, donc la majeure partie de l'image est réglable à partir du panneau Ajuster.
La mise en surbrillance prend Aucun, JavaScript, TypeScript, Python, Java ou un profil partagé pour C, C++, C# et Go. Le téléchargement d'un fichier sélectionne le profil à partir de son extension, donc un fichier .cs ou .go arrive déjà coloré. Vous pouvez également supprimer entièrement le surlignage et écrire le tout dans une seule couleur d'encre, ou colorer un fragment sélectionné à la main lorsqu'une ligne mérite l'attention.
L'arrière-plan est Papier ou Tableau noir, et le choix s'applique aux images exportées, pas seulement à l'aperçu. Quel que soit celui dans lequel votre public lit le code, c'est celui-là qu'il faut choisir.
Le stylo est la partie qui compte, car c’est le stylo qui écrit. La vitesse va de la moitié au double. La pause de ligne le maintient entre les lignes pendant une seconde maximum, moment où un extrait cesse d'être un mur et commence à être une séquence. Dans la vue du stylet 3D, Pen lift définit la hauteur de la pointe entre les traits ; celui-ci est un look plutôt qu'un changement de timing, et cela n'a aucun effet sur le rendu 2D plat.
Les identifiants longs sont la raison habituelle pour laquelle une ligne ne rentre pas. En mode texte, la taille varie de 70 à 140 pour cent et l'espacement des lettres va jusqu'à 0,2em, ce qui est normalement suffisant pour conserver un nom de méthode long sur une seule ligne. Le cadrage de la caméra effectue un zoom entre 75 et 200 pour cent si vous préférez recadrer plutôt que réduire le texte.
Le format est 16:9 de large ou 9:16 vertical, donc une bobine et une page de documentation peuvent sortir du même extrait. La lecture s'interrompt, se rejoue et se déroule quand vous le souhaitez, sur une chronologie réelle plutôt que sur un seul bouton de lecture. Il y a plus que cette liste ; le panneau Ajuster mémorise ce que vous avez défini et il y a une réinitialisation lorsque vous êtes allé trop loin.
Ce qui fonctionne et ce qui ne fonctionne pas
De longues lignes peuvent être ressenties, et c'est à la verticale qu'elles font mal. Sur une image de 9:16, les lignes courtes gagnent ; si l'extrait insiste pour être large, utilisez 16:9 ou réduisez-le. Un mur de code est pire que trois lignes avec une pause après chacune. Les commentaires se lisent mieux que les identifiants intelligents pendant que le stylo écrit.
30 ips est le plus fluide des deux, mais l’écriture manuscrite n’en a pas besoin. 24 est suffisant et la taille du fichier est sensiblement inférieure, donc 24 est ma valeur par défaut et 30 est ce que je recherche uniquement lorsque le stylet se déplace rapidement.
Trois limites à connaître avant de coller :
- La saisie est limitée à 100 Ko et seules les 500 premières lignes sont dessinées.
- La police de glyphe dessinée à la main est ASCII imprimable, donc les caractères accentués apparaissent sous la forme d'une petite boîte et Scribe vous indique quand cela se produit. Mon propre nom de famille n’y survit pas.
- Le rendu et l'encodage se font sur votre machine, donc un long clip ou un dessin dense y est ressenti.
Ce dernier est l’échange derrière l’aperçu gratuit. Votre texte, votre code, votre dessin et chaque image rendue restent dans le navigateur ; la seule chose qui reste à l'export est le format et la durée du rendu, car le compteur journalier doit être appliqué quelque part. Le FAQ cela explique cela, ainsi que le moment de la réinitialisation.
Là où un navigateur ne peut pas encoder MP4, vous obtenez WebM à la place, et Scribe le dit plutôt que d'échouer silencieusement. Chaque limite ci-dessus est sur la liste à améliorer, et le faire sans envoyer votre code nulle part est la contrainte que je préfère contourner plutôt que de la supprimer.
Exporter et où le mettre
L'exportation est en 720p ou 1080p, 24 ou 30 ips, large ou verticale. Avant de dépenser quoi que ce soit, Scribe affiche une estimation : la durée, le nombre d'images et approximativement le nombre de mégaoctets que vous êtes sur le point d'obtenir. Connectez-vous pour télécharger ; l'aperçu qui vous a amené ici ne demandait pas cela. Si cinq exportations par jour ne suffisent pas, le page de tarification est la réponse honnête.
Ensuite, le fichier doit atterrir quelque part où il mérite sa place. Les miens portent principalement sur les descriptions des pull request, sur les changements où le raisonnement compte plus que la différence. Les notes de version sont la deuxième meilleure maison : un clip de 40 secondes est regardé où un journal des modifications défile. Après cela, la page de documentation pour la fonction que tout le monde a mal interprétée, la chaîne Slack où les explications écrites vont mourir, et un fil de lancement, où un clip vertical fait le travail qu'une capture d'écran ne peut pas faire.
La vidéo, réalisée avec l'outil qu'elle décrit
C'est l'extrait du haut de cet article, exporté directement depuis Scribe. Pas de caméra, pas d'éditeur, pas d'enregistrement d'écran : juste le stylo qui écrit le code dans l'ordre qui rend le bug évident.
L'aperçu est gratuit et ne nécessite aucun compte, donc le moyen le plus rapide de juger de tout cela est de coller votre propre fonction la moins bien expliquée dans Scribe et regardez le stylo fonctionner. Si cela tient, vous le saurez dans une minute. Si ce n’est pas le cas, je préférerais savoir pourquoi.
Pour le plus large fonctionnalités du développeur, voir prix, puis comparez le flux de travail pas à pas du code.