A Universe of Sorts

the Ocaml-git project is a re-implementation of git in OCaml. It's well-written, and I was walking through the codebase, when I found absolutely amazing, hilarious, and deep comments from dinosaure. I really enjoyed reading through the codebase, and the existence of these comments made it more humane to read. I don't know who dinosaure is, but I'm really glad they wrote the comments they did, it really made my day.

§ The one that takes a stab at Haskell for fun

(* XXX(dinosaure): ...we can fix this detail butI'm lazy like haskell. TODO! *)

§ The academic one that broken-links to a paper

(* XXX(dinosaure): see this paperhttps://github.com/ocamllabs/papers/blob/master/irmin/2014.08.matthieu/rapport.pdf *)

§ The one about the frustrations of bug-hunting

(* XXX(dinosaure): [~chunked:false] is mandatory, I don't want to explainwhy (I lost one day to find this bug) but believe me. *)

§ The one about a potential heisenbug

(* XXX(dinosaure): if, one day, we find a bug about the serialization of theIDX file, may be it's about this function (stable/unstable sort). *)

§ The requisite comment in french for an OCaml project

(* XXX(dinosaure): bon ici, c'est une note compliqué, j'ai mis 2 joursà fixer le bug. Donc je l'explique en français, c'est plus simple.En gros, [Helper.MakeDecoder] utilise ce buffer comme buffer internepour gérer les alterations. Ce qui ce passe, c'est que dans lafonction [refill], il s'agit de compléter à partir d'un [input](typiquement [zl]) le buffer interne. C'est finalement un__mauvais__ jeu entre un [Cstruct.t] et un [Bigarray].Il s'agit de connaître la véritable taille du [Bigarray] et derajouter avec [blit] le contenu de l'[input] si la taille du[Bigarray] (et pas du [Cstruct]) est suffisante.Avant, cette modification, [zl], [de] et [io] partagaient le même[Bigarray] découpé (avec [Cstruct]) en 3. Donc, dans le[MakeDecoder], [refill] considérait (pour des gros fichiers faisantplus de 0x8000 bytes) que après [de], nous avions encore de laplace - et dans ce cas, nous avions [io].Ainsi, on [blit]ait [zl] dans [de+sizeof(de) == io], et finalement,on se retrouvait à essayer de décompresser ce que nous avionsdécompressé. (YOLO).Donc, on considère maintenant [de] comme un [Cstruct.t] et un[Bigarray] physiquement différent pour éviter ce problème.Cependant, il faudrait continuer à introspecter car j'ail'intuition que pour un fichier plus gros que [2 * 0x8000], ondevrait avoir un problème. Donc TODO. *)

§ The deep one