Constructors

[joshka]

Originally posted by @kdheepak in #736 (comment)

In languages like Python, all of these can build a Block:

Block(title = "title", borders = "all")
Block(borders = "all", title = "title")
Block(borders = "all")
Block()

In Rust, we have to use this pattern for the same benefits (not breaking future features, configuration of defaults, changing order in which you set fields, etc):

Block::new().title("title").borders(Borders::ALL)

which my understanding of is why it the convention for building structs.

Also, you can build a Block without a title using Block::new().borders(Borders::ALL). Along the same lines of the Paragraph point you pointed out, Block::new(title, borders) implies these are required and doesn't hint at other options (e.g. padding). It also is easier to end up breaking in the future if we decide to add a new field that is of equal importance to title and borders.

fwiw, I like that Paragraph::new takes text because as you said it is useless without content. But I also don't remember every new function in ratatui and their signatures. I don't want to change Paragraph::new or for example the constructor for Table::new, I was trying to give an example where what I type on autopilot doesn't work and the cognitive overhead of different ways of constructing something.

Also, it is generally way faster for me to type SomeWidget::new().<TAB> and wait for autocomplete to give me options than it is to type SomeWidget::new(<TAB>, then complete the required arguments, and then continue with SomeWidget::new(...).<TAB> to look for more options. I find it ergonomic when I get . autocomplete for all available optional configuration.

[joshka]

On the cognitive load part - your LSP should handle telling you what parameters are required.

On the faster part - if you want that, I'd suggest that this use case should be using .default().<TAB> and not new(). A lot of the new() constructors were added recently IIRC, and we did so without really thinking through what the useful parameters to be added should be. A case in point is Table::new() which did not have widths.

If constructors are always empty, then there's no point in having a Default trait at all. default() is the empty constructor.
In fact, I'd be for generally avoiding empty new() methods entirely once traits can be const.

I think where I differ from your perspective is that I see constructor methods as a convenience idiom in rust, not the same as a constructor which is the only way to crate items in other languages. So it allows for the idea that a rust constructor is supposed to be used for most common use case, and not just to provide the required fields.

In ratatui, we've inherited types that act both as builders and the runtime value in the same object, which makes things a bit painful to play with, as such we sort of run into these sorts of slightly ambiguous idiomatic things which would not be there if we had actual builder types. So we make do with that and try to come up with fairly reasonable set of APIs that walk that line between builders and constructed types.

In the end, my argument for making title and borders parameters to Block::new() stems from looking at a very small sample of the callers of the new() method and of Block::default(). The big reason to contemplate changing this now is that Block::new() has 171 files vs Block::default()'s 1.4k, so we're at a point where we could easily fix the problem without too much hassle (deprecate new() pointing at default(), leave it for a while, then add the useful params to new()). If we leave it too long then that shp sails and we never get a new() method with parameters and have to rely on creating named construtors instead.

[kdheepak]

I think those are fair points.

w.r.t

If constructors are always empty, then there's no point in having a Default trait at all. default() is the empty constructor.
In fact, I'd be for generally avoiding empty new() methods entirely once traits can be const.

From: https://rust-lang.github.io/api-guidelines/interoperability.html#types-eagerly-implement-common-traits-c-common-traits

Note that it is common and expected for types to implement both Default and an empty new constructor. new is the constructor convention in Rust, and users expect it to exist, so if it is reasonable for the basic constructor to take no arguments, then it should, even if it is functionally identical to default.

I think there's an expectation at the very least from users that ::new() exists and does the same thing as ::default() unless there's a good reason not to.

I agree that this is largely due to the fact that we don't have builder structs.

[kdheepak]

We are in essence following the builder lite pattern.

https://matklad.github.io/2022/05/29/builder-lite.html

If builder methods are to be used only occasionally, with_foo is the best naming. If most call-sites make use of builder methods, just .foo might work better.

[joshka]

Yeah, I think you might be right on new and default peacefully co-existing

[Valentin271]

If constructors are always empty, then there's no point in having a Default trait at all. default() is the empty constructor.
In fact, I'd be for generally avoiding empty new() methods entirely once traits can be const.

Going even further, if new and default do the same thing, then only default should exist IMO as it takes no space, i.e. a new initializing fields with default values is essentially boilerplate code and useless.

If new does something particular though it should exist. In the case of block, default should use the default of Borders (which is no borders, whether this should or shouldn't be the default is debatable) and, new do the opposite, in this case ALL. But I see no point having a two API endpoint doing the same thing. (of course excluding traits, and thus default, can't be const)

I think there's an expectation at the very least from users that ::new() exists and does the same thing as ::default() unless there's a good reason not to.

I actually expect the opposite, if both exist I expect them to do different things.
In ratatui I always get lost: "Wait there's a new and default? which one should I use? Are they even doing the same thing?". If new has parameters it's all sorted, I know it's different and I can configure the important/most used values.

---

More generally I always feel like default - because it's a trait and is usually derived - is missing documentation. From the lsp the documentation is

Returns the “default value” for a type.
Default values are often some kind of initial value, identity value, or anything else that may make sense as a default.

Which doesn't mean anything. Or even worse, means different things to different people.

---

TLDR;

According to me:

• default is the default of every field, depending on the fields default impl, this might be a good/bad option (in the sense of usefulness).
  e.g. For me Block::default() is useless because I always want borders but Style::default makes a lot of sense because it's always different
• new is the goto when you are starting, i.e. it has useful parameters if needed (Paragraph is a good example), and if no parameters are needed then it doesn't exist because it would be the same implementation as default
• other specialized constructors, bordered, styled, from_env ... are overload constructors as in C++/Java and nothing more.

[EdJoPaTo]

This seems like a different side of #978. #978 is about having only useful structs while ::new() without arguments could be part of a builder-lite pattern…

As outlined in the linked issue I think the only useful struct approach is better in most cases. Only a few structs have multiple different ways like Style or Block so they can exist on their own and have no minimal required content.

Example: Block::new().title("") or Block::new().borders(Borders::TOP) are two ways starting at the same point. A chart::Dataset without data is pointless (literally rendering pointless 🤡).