# Style proposals for Rust 2024 edition Process proposal: evaluate consensus and likely community acceptance independently, ignoring rustfmt feasibility during initial review. rustfmt team will raise any issues with feasibility and we can evaluate those at that time. ----- Link for rustfmt options: https://rust-lang.github.io/rustfmt/?version=v1.5.1&search= ----- [`format_code_in_doc_comments`](https://rust-lang.github.io/rustfmt/?version=v1.5.1&search=#format_code_in_doc_comments): modify default to true I think rustfmt should not be ignoring these, I think it should format them like any other code. Caleb: agreed in principle, somewhat worried in practice about the feasibility of this for 2024 given the number of known bugs and outstanding questions/requests (e.g. we've got users that want the ability to utilize an entirely separate formatting configuration for code in doc comments) MG: Yes, feel like "users want the ability to have different formatting in doc comments" seems really.... niche Jane: Yes, I've always wanted this, super annoying when doc comment code isn't formatted nicely. Only concern is the offset caused by the comment itself and how it interacts with line numbers, assuming the answer is that you will just end up with slightly squished formatting because you're using 4 fewer characters before you reach the line length limit, which doesn't seem like an issue. MG: Or even more chars lost, given impl items, etc. Josh: We should make sure `format_code_in_doc_comments` is stabilized as an option, so that people can choose to disable it if they want different formatting. Beyond that, rustfmt may choose to add more configuration options in the future, but I don't think that should be a blocker. consensus on targeting 2024 (? do we have this) ----- `doc_comment_code_block_width`: modify default to match `max_width` (e.g. changing max_width changes this to match unless set explicitly) Caleb: unsure about this one. we introduced this option originally based on info that was shared about non-ideal formatting behavior for these code blocks in prominent places like docs.rs. the default value for this one can have subtle, but pretty significant impacts Josh: Would like to know more about what Caleb is saying docs.rs uses this for. AFAICT, this still defaults to 100 right now, which is the same as `max_width`? Jane: Confused how this is being used by docs.rs MG: Fine with this. not full consensus, caleb has reservations ----- `comment_width`: modify default to `max_width` (Currently comment_width has a lower default of 80 whereas max_width has a default of 100; I think it should be the same width. with comment_width inheriting max_width unless explicitly overridden) Caleb: Agreed, findings explaining why these are different - https://github.com/rust-lang/rustfmt/issues/3349#issuecomment-1460751390 MG: Especially b/c there seems to not have been a good reason for this to differ, I'm ok w/ this :thumbsup: Jane: Inclined to agree, wants to understand motivation behind differences Josh: Agrees :) TC: some historical observations/studies/research showing differences in readability between english prose and code, latter is more sparse and easier to let run longer likely consensus, but want to review aforementioned research TC shared ----- [`format_macro_matchers`](https://rust-lang.github.io/rustfmt/?version=v1.5.1&search=#format_macro_matchers): modify default to true MG: Kinda dislike, people sometimes format their macro matchers specifically to give context about how the macro is used. MG: analogs to formatting bodies, somewhat of a dsl and largely just regrouping tokens Jane: Would like to see where it goes. Want to have people experiment with it and get feedback, and like things to be consistent + not have to think about it. Would like to include it in the unstable 2024 style edition, and wait for objections (e.g. have to add `rustfmt::skip`) caleb: objection on the basis of this hasn't been specified by t-style, we'd need to make these rules first before we can enable in rustfmt by default (thumbs up) MG: Agree that codifying it is a prerequisite Josh: Would like to see examples of what MG mentioned, have not seen that in the wild and would like to. Josh: agreed with Jane wrt shipping nightly style edition as early as possible Josh: wrt style guide, agreed this would need to be in the style guide Caleb: like this as something we should do, mildly opposed to getting it into 2024 no consensus, needs more discussion [caleb-post-meeting-addition]: rustfmt mostly attempts to apply formatting rules for standard Rust syntax by doing some shenanigans to make the macro contents "look" like standard Rust, but here's a reported case where rustfmt doing that application of standard Rust syntax rules is problematic https://github.com/rust-lang/rustfmt/issues/5680#issue-1561603693 and where I feel we don't have any clear guidance on what should be done ----- Modify all sort orders to use version-sorting. For instance, a1, a2, ..., a10, a11. (This does not change whether any given item is sorted alphabetically or ASCIIbetically.) I think this is strictly an improvement over the current state; the only thing it changes is making sure we don't do a1, a10, a11, ..., a19, a2, a20. Definition: To version-sort two strings find the longest common prefix between them, then if the point at which the strings diverge is in the middle or at the beginning of an ASCII number (series of ASCII digits) in both strings, compare the two numbers numerically rather than comparing byte values. If either or both strings have leading zeroes, compare them as if they have a leading decimal point (e.g. 0001 < 0002 < 001 < 1). (Caleb notes: "fwiw i _think_ rustfmt does this correctly with version=Two, so seems like a borderline inevitable candidate anyway") MG: :thumbsup: Caleb: in favor, but want to be 100% confident current version=Two behaivor indeed matches - Josh: Happy to help supply test cases (beautiful, thank you!) Jane: no objections likely consensus ----- `group_imports`: modify default to `StdExternalCrate` Fairly uncontroversial, many people do this already. MG: Strong yes Josh: As the proposer I'm in favor, but I want to note that at least one person on Zulip did bring up that they weren't a big fan of this and preferred another style. https://rust-lang.zulipchat.com/#narrow/stream/357797-t-rustfmt/topic/ExternalCrate.20import.20grouping I'm not suggesting that as a reason to *stop*, just that I don't want us to think "everyone obviously wants this". Jane: Strong yes as well Caleb: weakly agreed. I see the benefit in having a standard grouping prescribed in the style guide, but i haven't experienced enough different standard groupings to have a strong opinion on what the _best_ default grouping would be. also curious whether t-style thinks that std -> external -> crate is the best overall, or is it just the best that can be done under current rustfmt constraints? ---prior caleb comment that predates process Caleb: just for awareness the same implementation vs. timeline challenge for rustfmt wrt maintaining comment association (this comment predates our current process. caleb would like to do this, would like to do so for 2024, but it might be tricky for us to fix current bugs in time) ---prior ----- `use_field_init_shorthand`: modify default to true https://rust-lang.github.io/rustfmt/?version=v1.5.1&search=#use_field_init_shorthand Slightly more opinion-based, but I think it's a useful change that just didn't exist when the style guide was created. MG: Strong yes Jane: +1. Prefer concise Caleb: Yes Note: field init shorthand was added in Rust 1.17, so using this won't break people's MSRV. ----- `overflow_delimited_expr`: modify default to true Relevant (but long, community feedback in favor of making this change): https://github.com/rust-lang/style-team/issues/149 https://rust-lang.github.io/rustfmt/?version=v1.5.1&search=#overflow_delimited_expr More food for thought? https://github.com/rust-lang/rustfmt/issues/3370#issuecomment-1288226646 Another more opinionated one. MG: :thumbsup: Caleb: indifferent. good to make the change if the team wants to Jane: lean towards +1. don't like the extra indentation when split with the newlines, seems like it could reduce noise Josh: +1. This will also improve as we improve the "short" heuristics. Consensus: agreement ----- `reorder_impl_items`: modify default to true This moves associated types and consts to the top of impl blocks, above methods. People tend to do that already, so I don't think this will be controversial. MG: ~~Weakly in favor, though I wish this is something folks could do in batch rather than when rustfmt runs on save or something. Kinda orthogonal to rustfmt though. I know this is a refactoring option in rust-analyzer.~~ MG: May change to indifferent or weakly opposed because this is a lot more disorienting than other formatting Josh: would expect in general that changes in the style edition will get applied in batch: people will update their style edition, `cargo fmt`, then commit the result. We should recommend against people updating the style edition and *not* mass-reformatting, for this exact reason (formatting happening piecemeal on save). MG: Also concerned about code moving around when writing new code. Caleb: conceptually in favor Jane: Might not being following, but not same intuition as what Michael articulated. writes things & hits save button based expectations around what currently working on. Leaning in favor, like code matching generated documentation No consensus, more discussion needed prior comment from caleb that predates current process (tl;dr, an implementation concern in rustfmt) ------ Caleb: not controversial/not opposed, but rustfmt has a lot of issues maintaining proper comment associations when reordering things ----- ----- Finally, the large and likely controversial one: I'd like to rework the "small" heuristics substantially, so that we have fewer cases of wrapping 40-character-wide lines that rustfmt just decides are too complex. I have some heuristics in mind that we could experiment with. If we can't come up with a good alternative heuristic, I'd like to consider something like changing chain_width to max_width. Caleb: Style guide already defers to unspecified heuristics. "i'm completely open to any new rules that overall produce better defaults." Don't want to just change the width values, though. Josh: Hoping to get to an initial consensus of "there's value in looking for better heuristics", with some requirements for those heuristics (e.g. "should be intuitive for humans", some of our other general style-guide requirements), and then if so, start looking for those heuristics. I do have some initial ideas in mind and would love to figure out a good way to test them over large codebases. Not looking to decide those heuristics today.