[easy] Fix whitespace, formatting, prettify the code

[aantron]

When code doesn't look good, it is difficult to read and understand. We want Lwt to be easy to work on.

Basically, if you run into any strange indentation, please go ahead and fix it :) Here are some immediate examples from the recent past: [1] [2] [3] [4].

It's recommended not to do this to a file that has an open, recent pull request, to avoid a merge conflict. "Recent" is probably less than a couple months old. Also, check any in-progress or easy issues for an idea of what is being worked on. On the other hand, don't worry too much – in case of a bad conflict, maintainers exist to make sure nobody has to do too much merging work :)

In particular, at the moment, lwt.ml (#354) probably shouldn't be touched, although you can edit the new one's whitespace by opening pull requests against the wat branch that #354 comes from.

Some pointers:

• Lwt uses 80-column lines. Comment lines should use up as much of that as possible.
• Two-space tabs (tabs as spaces!).
• I obviously prefer the formatting as in lwt.ml: human-friendly edition – major refactoring and commenting of the Lwt core #354 (example), but any improvement is welcome.
• If you know how to use ocp-indent, teach us/me, or tell what it's capable of :) Thanks @Richard-Degenne, @vasilisp!
• If you want to discuss what the whitespace should be, please go ahead!

This is an ongoing issue. Known to be in progress or done:

• ocp-indent applied to lwt_stream.ml (Added .ocp-indent rules and fixed lwt_stream indentation #400, @Richard-Degenne).
• ocp-indent applied to the rest of the OCaml files (Indented most of the source code #409, @Richard-Degenne).
• clang-format applied to C files (Formatted C files #416, @Richard-Degenne).

[Richard-Degenne]

One way to enforce sensible indentation throughout the whole codebase would be to add a .ocp-indent file to the project. That also means that if a developer has ocp-indent installed in their editor, it will automatically follow the same indentation rules when editing / writing code.

I'll try to format some files with the default settings, just to see how it looks.

[vasilisp]

We have the following .ocp-indent in most Ocsigen repos:

normal
with=0
syntax=lwt mll
max_indent=2

I am surprised that there isn't one in Lwt already. I don't know how much our configuration differs from the default, but its results are in line with the established OCaml style and with @aantron's example (I think).

[Richard-Degenne]

Yes, these are also my default settings (used when I don't have a .ocp-indent inside the project).

If this is standard inside Ocsigen projects, I can go ahead and add it, then start "normalizing" existing files to match these settings.

[aantron]

That sounds reasonable. How about converting one file first, say something large like lwt_unix.ml? That should give a good idea of what the settings will do. I'm scared of applying it to the whole codebase right away :)

Also, is it still easy to separate history into whitespace-only and logic-changing commits when using ocp-indent in a text editor? Or does it encourage conflating the two by making whitespace changes too eagerly?

[aantron]

Scratch that, lwt_stream.ml instead of lwt_unix.ml. I think that is the least likely to cause conflicts with anyone's work.

[Richard-Degenne]

Also, is it still easy to separate history into whitespace-only and logic-changing commits when using ocp-indent in a text editor? Or does it encourage conflating the two by making whitespace changes too eagerly?

Well, this is entirely up to you, and the way you use your editor; ocp-indent is only here to help the editor auto-indenting the code.

In Vim, for example, you can

• Have a new line correctly indented after you hit Return;
• Type == to auto-indent the current line;
• Auto-indent any block of lines you want with the Visual mode;
• Auto-indent the whole file with gg=G.

I don't know much about Emacs and VSCode, but I'm sure they have similar features.

[aantron]

Ok, that sounds good :)

[Richard-Degenne]

I've pushed a first commit where I've indented lwt_stream.ml and its mli using the settings given by @vasilisp. It looks ok. There is one thing bothering me, though: the lack of indentation after a match clause makes it difficult to discern the block and the following match clause (example).

There is an option in ocp-indent to change that, just tell me what you think.

Also, is it too early to open a PR, or should I open one and mark it as a WIP for the time being?

[aantron]

It looks pretty good, actually. The only thing I'd say ocp-indent got wrong is the deprecation annotations ([@@ocaml.deprecated]), but maybe we can survive that. If it's not configurable, maybe we can PR to ocp-indent in the future. Or maybe I'm wrong, and ocp-indent is right :)

For the match cases, I eventually agreed with indenting like ocp-indent does. I've taken to inserting blank lines when that makes the next match case difficult to find. We can insert them manually later (or now), in a hand-crafted prettification pass :)

If you want to go through the whole file and make it beautiful, go ahead :) But I think this is already helpful, and worth a PR on its own.

[aantron]

Thanks for the change. If willing to do more, I think basically the only files currently being worked on are src/core/lwt.ml and src/unix/lwt_unix.cppo,ml[i]. Everything else is fair game for ocp-indent. Might be too tedious, though :)

[Richard-Degenne]

About the C files, there is clang-format, which natively support Google-style formatting.

I'll give it a shot later today.

[aantron]

Most of this has been done by @Richard-Degenne (thanks!). For ongoing formatting work, we just do it as we go, and, if needed, we can write a single sentence in CONTRIBUTING to encourage others to do it.