Why does Jane Street's style guide use double semicolons (;;)?


#1

I’m trying to write a style guideline and we’re mostly agreeing with Jane Street. I’m trying to figure out why they recommend separating top-level statements with ;; though. Everything I can find about this says they’re a useless historical thing, so why does Jane Street recommend using them?


#2

AFAIK it makes the error boundary smaller in case of a syntax error.


#3

Have you considered adopting ocamlformat for cosmetic concerns? It might not always produce ideal formatting, but ideal formatting is subjective, and we like not having to think about cosmetic rules even though manual formatting and linting can produce better results in certain cases. It also provides a very nice developer experience and makes code reviews more effective.


#4

Unfortunately ocamlformat’s rule “try to fit as much stuff on one line as possible” is pretty much the opposite of what we want, and it sounds like it’s a fundamental part of its design.

(It’s also really annoying that the indentation rules are inconsistent and frustrating that it has its own style rules instead of adopting any existing community style, although I could probably force myself to live with that if necessary)

I’m glad someone is making this tool but so far it’s not meeting our needs.


#5

That’s a good point. I thought I’d mention it because it feels like ocamlformat is a tad underrated around here. It allowed me to pick up OCaml syntax coming from Reason, and I’ve actually come to prefer both ocamlformat over refmt and OCaml syntax over Reason syntax. I don’t think I would’ve been able to adopt OCaml so easily without it, and find myself wishing projects I’d like to contribute to had their own .ocamlformat file as it would make me much more confident submitting a PR, no matter what their ocamlformat config contains.

I started using Jane Street’s fork of ocamlformat at first, then switched to the git version with a heavily customized config. But I’m very happy now with the latest version of ocamlformat with just “profile = sparse” in it, and I don’t feel like it tries to put as much as it can on a single line.

Edit: There’s also now a “janestreet” profile and from what I’ve read, Jane Street is in the process of adopting it.


#6

No good reason. Don’t use double semicolons. They are part of the OCaml toplevel syntax and shouldn’t be used in OCaml programs. The exist in OCaml syntax only for backward compatibility with Caml light.


#7

I’d really appreciate you getting your concerns onto the ocamlformat issue tracker so they can be tracked; particularly if you have a counter example of formatting you’d like.

It had to start somewhere :slight_smile: See this post for a pointer to the community guidelines and ocamlformat’s integration with it (thanks to @gpetiot

I realise that formatting style discussions can never converge fully, but I’d really like to see a “good enough” mechanical formatter becoming accepted for our larger codebases. It’s especially important to get opinions from maintainers of codebases that consider the current approach not fit for their purposes at the moment…


#8

Yup, that’s exactly the upside of double-semis. They’re kinda ugly, but they make for better error messages.

FWIW, we do use a patched version of OCamlformat internally, and we’re working with upstream to synchronize our changes with that. You’ll be able to adopt our style at that point easily enough if you want.

You can see what it looks like here:

Core_kernel (and a large fraction of our libraries) use OCamlformat these days.

y


#9

Since OCamlformat creates code that by definition has no syntax errors, I can’t see the argument for having them in the final code. You could use them during development but let OCamlformat remove them once the syntax is known to be correct.


#10

What if you edit the code later? :slight_smile:


#11

Since OCamlformat creates code that by definition has no syntax errors, […]

That’s wrong. OCamlformat formats code that contains no syntax error. It will refuse to work on code that doesn’t parse. So the problem needs to be handled before and outside of ocamlformat, and therefore it makes sense for ocamlformat to leave the ;; if you want them.


#12

What exactly is wrong about saying OCamlformat emits code that is syntactically correct?

I was assuming a workflow where you edit code and include ;; for better error messages until you are satisfied but then use OCamlformat before submitting it. At this step, the ;; would be removed.


#13

I think the problem with this is that it’s very rare to have “final code”. Running my formatter (or even commiting a change) doesn’t mean I’m never going to edit a file again, and if I want ;; when I’m first writing code, then I probably want it next time I’m editing the file too.


#14

I have yet to use it, but I hear ocp-indent might be better at following “normal” styling.