[wg-camlp4] Changes to the parsetree

[Daniel Bünzli]

Le mardi, 26 mars 2013 à 13:49, Thomas Gazagnaire a écrit :

> (eg. you usually read what the function / module does before reading its signature).
[...]  

> A lot of existing code doesn't follow this convention (JS' core for instance). Personally, I found clearer to read what the function/type/module does in a comment, before reading its signature.

I also write them after. I think that for *libraries* the "usually you read what the function does before reading its signature" is quite debatable.  

For a library maybe once or twice you will read an interface from top to bottom, but that's not the average use case. Most of the time you want to first *find* a function and then consult its signature (often a brain refresh on that is sufficient) and *maybe* read the documentation.  

From that perspective making the comment after makes it easier to skip from one definition to the other: just look for what follows a blank space.  If comments are before, you have to look for blank space and then move up again, which incurs direction changes that slows down your scanning. (For those that object that CTRL-s does the scanning, I respond that your brain sometimes doesn't remember the exact name you are looking for).  

Besides having comments after also matches the order in which it appears in the generated html, which makes it easier for my brain to switch from one representation to the other.  

These may seem like details, but I think they are relevant from a human factor point of view.  

Best,

Daniel