Ce guide de style émet des considérations générales pour le style attendu de votre code dans le cours. Le but est d’avoir du code compréhensible et propre. Ce guide sera utilisé lors de la correction des TPs pour attribuer une note sur le style du code.

Compilation

Tout code rendu doit compiler. Un TP rendu qui ne compile pas avec les instructions données dans l’énoncé se verra attribuer une note de 0/100.

Warnings

Le compilateur d’OCaml émet des warning dans certains cas. Par exemple, le code suivant contient un filtrage par motif non exhaustif :

(* Mauvais code *)
let empty_list l = match l with
| [] -> true

En le compilant, on obtient le warning suivant :

1 | ...................match l with
2 | | [] -> true
Warning 8 [partial-match]: this pattern-matching is not exhaustive.
Here is an example of a case that is not matched:

Tout warning dans un TP rendu résultera en une pénalité sur la note de qualité de code.

Commentaires

• Les commentaires doivent aider à la lecture du code.
• Les commentaires redondants sont à éviter

Annotations de types

• On vous demander d’annoter au minimum le type des paramètres et le type de retour de toutes les fonctions principales définies dans un fichier. Par exemple :

let rms (x : float) (y : float) : float =
  let square x = x *. x in (* pas nécessaire d'annoter les types ici, c'est une liaison locale *)
  ((square x) +. (square y)) /. 2

Nommage de variables et de types

• Les noms de liaisons, types, et modules doivent avoir du sens.
• Les noms à une seule lettre ne sont à utiliser que très localement.
• La convention de casse est :
  • le snake_case pour les liaisons
  • le PascalCase pour les constructeurs de types
  • le PascalCase pour les noms de modules
  • le ALL_CAPS pour les types de modules.
• L’utilisation de synonymes de types ou la définition de nouveaux types est fortement recommandée pour aider à la lisibilité. Par exemple, on préfère un type coord = (int, int) pour décrire des coordonnées en 2 dimensions, ou mieux encore, un type coord = { x: int; y: int }.

Indentation

• Le style d’indentation doit être consistant. Vous pouvez utiliser l’outil ocamlformat pour faciliter la tâche.

Duplication de code

• La duplication de code est une mauvaise pratique. Si vous vous retrouvez à copier du code, réfléchissez à comment éviter de devoir le copier. Généralement, un refactor pour extraire le code à copier dans une fonction peut faire l’affaire.

Longueur de fonctions

• Les définitions fonctions seront de préférence courtes, entre 1 et 25 lignes.
• Éviter les lignes trop longues. Au delà de 120 caractères, il y a un problème.
• Utiliser des liaisons intermédiaires pour couper des lignes trop longues.

Fonctions interdites

• Les fonctions de la bibliothèque qui peuvent lever des exceptions sont à éviter. Par exemple, on préférera utiliser du filtrage par motif sur une liste pour extraire son premier élément (et avoir un comportement adapté si elle est vide) plutôt que d’utiliser List.hd
• Toute construction impérative (for, while, ref, :=, array) est à proscrire dans le cadre du cours.
• L’égalité physique (== et !=) est à proscrire, on utilisera uniquement l’égalité structurelle (= et <>).

Espaces

Attention à bien utiliser les espaces : mise à part l’indentation, on s’attend à un espace entre chaque symbole (pas zéro, pas deux, pas trois, …).

Par exemple, le code suivant est de mauvaise qualité :

(* Ne pas écrire son code comme ceci *)
let rms(x: float)(y:float) :float=
  let square x=x*.x in
  ((square x) +.(square y))/.2

La bonne manière de le formatter est la suivante :

let rms (x : float) (y : float) : float =
  let square x = x *. x in
  ((square x) +. (square y)) /. 2

Consistance de style

Il est important d’avoir un style consistant tout au long du même projet.

Autre ressource utile

Pour plus de détails, voir les guidelines de la documentation d’OCaml. En cas de désaccord entre le présent documents et ces guidelines, le présent document prévaut.