Stream: compiler development

Topic: zig-compiler - Formatter and style

Anthony Bullard (Mar 17 2025 at 11:31):

I want to make this thread so I can ask for pointed feedback on the style of the formatter and any general questions about expectations around formatting

Anthony Bullard (Mar 17 2025 at 11:32):

I have this EXTREMELY OVER COMMENTED block of code. Does this look how people could expect it to look if someone had typed this in? I.e., should this parse and format stably? (Please ignore \\ for zig multiline comments)

const stmt =
        \\import # Comment here
        \\    pkg # And here
        \\        .Something # Another one
        \\            exposing # Still commenting
        \\                [ # I really like comments
        \\                    func # Commenting for life
        \\                        as # Even here
        \\                            function, # And here
        \\                    Type # Commenting again
        \\                        as # And again...
        \\                            ValueCategory, # Why can't I stop?
        \\                    Custom # This is getting ridiculous
        \\                        .* # Even Uncle Bob is emabarrased
        \\                ] # And...I'm done
;

Joshua Warner (Mar 17 2025 at 11:38):

Seems not unreasonable

Anthony Bullard (Mar 17 2025 at 11:40):

I guess the big question is: is the principle that in a continuation where there is a comment not at end of line (and not in some collection) that we indent on the next newline and continue?

Anthony Bullard (Mar 17 2025 at 11:42):

Or should things like qualifier and identifier proceed at the same level of indent?

Anthony Bullard (Mar 17 2025 at 12:07):

The alternative would be:

const stmt =
        \\import # Comment here
        \\    pkg # And here
        \\    .Something # Another one
        \\        exposing # Still commenting
        \\            [ # I really like comments
        \\                func # Commenting for life
        \\                    as # Even here
        \\                    function, # And here
        \\                Type # Commenting again
        \\                    as # And again...
        \\                    ValueCategory, # Why can't I stop?
        \\                Custom # This is getting ridiculous
        \\                    .* # Even Uncle Bob is emabarrased
        \\            ] # And...I'm done
;

Anthony Bullard (Mar 17 2025 at 12:09):

I'll also write up an example with complex binops as well. There are SO many places where comments could be inserted there

Joshua Warner (Mar 17 2025 at 12:19):

On balance, less rightward drift seems good - but this is such an unusual situation that I’m not particularly concerned about it

Sam Mohr (Mar 17 2025 at 22:33):

I'd push for less rightward drift whenever consistently possible, so the second example is preferable to me

Brendan Hansknecht (Mar 17 2025 at 22:42):

Hmm. I think it should be consistent with what we would do for a function chain

x
    .y
    .transform()
    .run!()

So I would vote for this:

const stmt =
        \\import # Comment here
        \\    pkg # And here
        \\        .ExtraNesting # not sure this is actualy valid, but just an example of more nesting
        \\        .Something # Another one
        \\            exposing # Still commenting
        \\                [ # I really like comments
        \\                    func # Commenting for life
        \\                        as # Even here
        \\                        function, # And here
        \\                    Type # Commenting again
        \\                        as # And again...
        \\                        ValueCategory, # Why can't I stop?
        \\                    Custom # This is getting ridiculous
        \\                        .* # Even Uncle Bob is emabarrased
        \\                ] # And...I'm done
;

Richard Feldman (Mar 17 2025 at 22:46):

yeah I agree with that

Richard Feldman (Mar 17 2025 at 22:46):

I don't think anyone is actually going to write comments in all these places, so I don't think the quantity of indentation really matters here

Richard Feldman (Mar 17 2025 at 22:47):

I think what's more important is that if you put comments in a small subset of these places, it looks consistent with what we do elsewhere

Fabian Schmalzried (Aug 26 2025 at 07:53):

Hi, first thanks to @JRI98 for fixing the remaining multiline string issues that I caused.

While looking at the formatter I saw the following remaining issues, that I would like to confirm before taking a shot at them:

The formatter does not make sure files end in a newline. According to POSIX they should. But this will change probably all snapshots when implementing.

The formatter removes everything that is malformed. I think it should just put out the original code for malformed nodes. I'm not sure how easy that is to implement, but I could imagine that it's not that easy, because I noticed the ranges of the malformed nodes is not always what I would expect.

JRI98 (Aug 26 2025 at 08:08):

Hello. I actually ended up breaking more stuff :sweat_smile:
But I have a new PR that should finally fix it #8225. It should be easier if we track if the last printed node was a multiline string.

Regarding the newline at the end of the file, sounds good to me.

When it comes to malformed nodes, I have thought about it before, but it is a particularity of the snapshots, because when formatting a file outside of them, the formatter doesn't change the file if it doesn't parse correctly.
What we could do is mimic the same behavior for snapshots and only try to format if the input parses correctly. And it has been a source of fuzz crashes in the past, when it practice they wouldn't happen outside of the snapshotting environment.

Fabian Schmalzried (Aug 26 2025 at 08:27):

Ok, I will leave the malformed nodes alone, just not formatting sounds way better.

I will have a look at the EOF newline. Probably easy to do. I think it's best to also update the snapshot tool to include the newline as part of the source and expect it as part of the formatted output. That should reduce the changes to the snapshots.

Last updated: Sep 09 2025 at 12:16 UTC