Guide de style AllenNLP

Leur priorité absolue en matière de style de code est qu'il soit facilement lisible pour un novice. L'apprentissage profond est facile à commettre, et ils souhaitent que le code soit suffisamment lisible pour que celui le consultant puisse réfléchir à leurs décisions de modélisation, sans chercher à comprendre ce qui se passe.

À cette fin, ils utilisent des noms descriptifs, des annotations de type et des docstrings cohérents. Dans le code manipulant des tenseurs, la plupart des lignes de calcul d'un tenseur comportent un commentaire décrivant sa forme. Lorsqu'une décision de modélisation intéressante ou importante est prise dans le code, nous écrivons un commentaire à son sujet (en ligne ou dans une docstring appropriée).

Docstrings

Toutes les méthodes publiques raisonnablement complexes doivent disposer de docstrings décrivant leur fonction de base, leurs entrées et leurs sorties. Les méthodes privées doivent également, le plus souvent, disposer de docstrings, afin que les lecteurs de votre code sachent ce qu'elles sont censées faire. Le schéma de base que nous utilisons pour les docstrings est le suivant : (1) une brève description du fonctionnement de la méthode, incluant parfois le comment et le pourquoi de son fonctionnement ; (2) les paramètres/arguments de la méthode ; (3) la valeur de retour de la méthode, le cas échéant. Si la méthode est particulièrement simple ou que les arguments sont évidents, (2) et (3) peuvent être omis. Notre documentation utilise le format Markdown ; les arguments et valeurs de retour des fonctions doivent donc être formatés sous forme d'entêtes Markdown (par exemple, # Parameters), présents dans presque tous les modèles ou modules du code source. Nous traitons la docstring de la classe comme la documentation des méthodes __init__, en y indiquant les paramètres et en omettant toute docstring sur le constructeur lui-même. Pour les constructeurs de modèles/modules et les méthodes comme forward, incluez toujours les paramètres et les valeurs de retour (le cas échéant) dans la docstring.

Format du code

Nous utilisons flake8, black et mypy pour garantir une cohérence de base dans le formatage. Ces directives de formatage suivent globalement le guide de style Python de Google, à quelques exceptions notables près. En particulier, comme nous utilisons des annotations de type et des noms de variables descriptifs, ils utilisent des lignes de 100 caractères au lieu de 80 caractères, et il est possible de dépasser ce nombre dans le code. De plus, nous utilisons mkdocs pour créer leurs documents ; les formats de docstring de Google ne s'appliquent donc pas.

Nommage

Ils suivent les règles générales de nommage de Google et leur définition de la CamelCase.

Disposition et importations des modules

Pour éviter que les fichiers ne soient trop volumineux, nous utilisons généralement une classe par fichier. Cependant, les petites classes indissociables d'une classe associée peuvent également être placées dans le même fichier (il s'agit souvent de classes privées).

Pour éviter toute verbosité lors de l'importation de classes ainsi structurées, il est conseillé d'importer les classes depuis le fichier __init__.py de leur module. Par exemple, la classe Batch se trouve dans allennlp/data/batch.py, mais allennlp/data/__init__.py l'importe, ce qui permet d'importer Batch depuis allennlp.data.

Les classes abstraites sont généralement placées dans un module contenant la classe abstraite et toutes les implémentations intégrées. Cela inclut des éléments tels que Field (dans allennlp.data.fields), Seq2SeqEncoder (dans allennlp.modules.seq2seq_encoders), et bien d'autres. Dans ces cas, la classe abstraite doit être importée dans le module ci-dessus, afin de pouvoir, par exemple, importer un champ à partir de allennlp.data. Les implémentations concrètes suivent la même structure que ci-dessus : à partir de allennlp.data.fields, importer un champ de texte.

Les importations doivent être formatées en haut du fichier, conformément aux recommandations de PEP 8 : trois sections (bibliothèque standard, bibliothèques tierces, importations internes), chacune triée et séparée par une ligne vide.

Conclusion

Certaines des conventions que nous avons adoptées sont arbitraires (par exemple, d'autres définitions de CamelCase sont également valables), mais nous nous y tenons pour conserver un style cohérent dans toute la base de code, ce qui facilite la lecture et la maintenance.