Hello Kakoune devs, I was trying to change some little stuff in the kakoune code base to get acquainted with it and so I noticed there is no .clang-format file given in the repo.
How do we handle the indentation of the code ? Are people against the use of an automatic formatting tool for any reason ?
This has been proposed a while ago by @ironzorg and my dislike for enforced formatting only grew since.
I would not be against having a .clang-format file in the codebase to document the general code style expected, however I really dont want that tool to have the last word, there is some context an automated formatting tool just cannot guess (for example that two parameters are closely related hence we dont want a newline inserted between them).
Why not add a STYLEGUIDE file in the root of the repo, or add it to the CONTRIBUTING file? In the JavaScript community there are a few published styleguides that are easy to point to and commonly understood. If there is such a thing for c++ out there that is similar to the conventions of this code base then maybe you could link to it.
I like autoformatting in my daily work because it stops meaningless or muddied commits where developers change each other’s indentation and other whitespace. This in turn makes it harder to follow changes when inspecting history and makes rebasing and reverting unnecessarily hard. I imagine that is not so much a concern here assuming you gate code style in pull requests, although if the contributor count goes up it could be a time saver.
Edit: Correcting mobile autocorrects.
I can try to create a .clang-format file that would fit the current code base, without applying it everywhere.
For people using clang-format, it can be simply disabled on a piece of code using:
// clang-format off
I would agree with the idea of having a STYLEGUIDE file. That one would take precedence over any indentation tool to dict what the community actually want. It would also help me write the .clang-format right.
I haven’t used clang-format specifically, but I have written a bunch of Rust code with and without automatic formatting.
In my experience, the absolute best part of fully-manual formatting is being able to manipulate the layout of the code in subtle ways to reflect the semantics. If a particular API takes a list of values but treats odd items as keys and even items as values, it makes sense to put the odd and even values on the same line instead of leaving them as an undifferentiated list. It’s possible to vary the operator spacing in an expression to highlight precedence. In Python (where single and double-quoted strings are semantically identical) I used to use double-quoted strings for human-readable content (like error messages) and single-quoted strings for machine-readable content (like network protocols) vaguely mirroring C’s distinction.
The downside of fully-manual formatting is the lack of consistency, which means it can be hard for a reader to know whether a given subtle change is an important clue or just noise. Sometimes an inconsistency is just a mistake, but also I’ve noticed my layout tastes change over the years, sometimes because I thought of an aesthetic improvement, sometimes just because I encountered a novel convention in another language and wanted to try it out (like when I discovered that Haskell’s style favours leading commas in lists). Mostly, though, my personal lexicon of subtle changes has very little relation to other people’s — just because I think layout A suggests interpretation B, there’s no guarantee anybody else will make that association, and they’ll just see my code change things up for no good reason.
Automatic formatting prevents me from making subtle improvements to layout, but it also prevents me from making things more confusing, and I’ve had enough code reviews to discover I cannot reliably predict which is which, so I expect to keep using automatic formatting wherever possible from now on for that reason alone. The fact that I can just type out a line of code, hit Save, and watch it automatically rearrange itself into something 80% as good as what I could do manually, with 0% of the effort, is the icing on the cake.