Foundations of API Design chapter #2994

tall-vase · 2025-12-05T13:29:11Z

Includes most of chapter 1 of foundations of API Design for Idiomatic Rust. Brought in from the gdoc. Tests have not been run locally yet, formatting has.

gribozavr · 2025-12-05T14:21:59Z

src/idiomatic/foundations-api-design/clarity-readability.md is being added, but it is empty and it is not linked from SUMMARY.md. Delete it?

(GitHub does not allow me to leave a comment on an empty file)

gribozavr · 2025-12-05T14:20:13Z

src/idiomatic/foundations-api-design.md

@@ -0,0 +1,3 @@
+---
+minutes: 2
+---


Do you intend to add something here?

Compare: https://github.com/google/comprehensive-rust/blob/main/src/idiomatic/leveraging-the-type-system.md?plain=1

At the very least, a title and {{%segment outline}} are needed.

gribozavr · 2025-12-05T14:28:44Z

src/idiomatic/foundations-api-design/meaningful-doc-comments.md

+It's important to write doc comments that developers will appreciate reading,
+that gives them the information they are looking for and doesn't just re-state
+the obvious.


Suggested change

It's important to write doc comments that developers will appreciate reading,

that gives them the information they are looking for and doesn't just re-state

the obvious.

Good doc comments provide information that the code, names, and types

cannot, without restating the obvious information.

More concise wording; more actionable ("information they are looking for" - not very actionable); more common spelling ("restate");.

gribozavr · 2025-12-05T14:30:17Z

src/idiomatic/foundations-api-design/meaningful-doc-comments/avoid-redundancy.md

+Function names and type signatures already document some information, avoid
+repeating them!


Suggested change

Function names and type signatures already document some information, avoid

repeating them!

Names and type signatures communicate a lot of information, don't repeat it in comments!

gribozavr · 2025-12-05T14:31:06Z

src/idiomatic/foundations-api-design/meaningful-doc-comments/avoid-redundancy.md

+/// Parses an ipv4 from a str. Returns an option for failure modes.
+fn parse_ip_addr_v4(input: &str) -> Option<IpAddrV4> { ... }
+
+// TODO: couple more of these, for the instructor to go through with students.


My favorite:

struct BusinessAsset { /// The customer id. let customer_id: u64, }

gribozavr · 2025-12-05T14:34:11Z

src/idiomatic/foundations-api-design/meaningful-doc-comments/avoid-redundancy.md

+```
+
+<details>
+- Motivation: Documentation that repeats name/signature information provides nothing new to the API user.


Suggested change

- Motivation: Documentation that repeats name/signature information provides nothing new to the API user.

- Motivation: Documentation that merely repeats name/signature information provides nothing new to the API user.

gribozavr · 2025-12-05T20:53:16Z

src/idiomatic/foundations-api-design/meaningful-doc-comments/who-are-you-writing-for.md

+```
+
+<details>
+- Motivation: It can be easy to fall into a pattern of writing only for you, but most documentation is for people coming in with a different perspective.


Suggested change

- Motivation: It can be easy to fall into a pattern of writing only for you, but most documentation is for people coming in with a different perspective.

- Background: The [curse of knowledge](https://en.wikipedia.org/wiki/Curse_of_knowledge) is a cognitive bias where experts assume that others have the same level of expertise and perspective.

- Motivation: Your reader does not have the same level of expertise and the same perspective as you. Don't write for people like yourself, write for others.

gribozavr · 2025-12-05T20:54:12Z

src/idiomatic/foundations-api-design/meaningful-doc-comments/who-are-you-writing-for.md

+
+```rust
+// TODO: What's a good illustration here?
+```


// expert writes for experts /// Canonicalizes the MIR for the borrow checker. /// /// This pass ensures that all borrows conform to the NLL-Polonius constraints /// before we proceed to MIR-to-LLVM-IR translation. pub fn canonicalize_mir(mir: &mut Mir) { // ... } // expert writes for newcomers /// Prepares the Mid-level IR (MIR) for borrow checking. /// /// The borrow checker operates on a simplified, "canonical" form of the MIR. /// This function performs that transformation. It is a prerequisite for the /// final stages of code generation. /// /// For more about Rust's intermediate representations, see the /// [rustc-dev-guide](https://rustc-dev-guide.rust-lang.org/mir/index.html). pub fn canonicalize_mir(mir: &mut Mir) { // ... }

gribozavr · 2025-12-05T20:58:47Z

src/idiomatic/foundations-api-design/meaningful-doc-comments/who-are-you-writing-for.md

+  much information.
+- Always ask: Is this documentation making it difficult for the API user? Are
+  they able to quickly grasp what they need or find out where they could need
+  it?


I'd also say something like "Experts also read API level documentation. Doc comments might not be the right place to educate your audience about the basics of your domain. In that case, signpost and namedrop - divert people to long-form documentation."

gribozavr · 2025-12-05T21:00:35Z

src/idiomatic/foundations-api-design/predictable-api.md

+
+# Predictable API
+
+Keep your APIs predictable through naming conventions and implementing common


Suggested change

Keep your APIs predictable through naming conventions and implementing common

Keep your APIs predictable by following naming conventions and implementing common

Parallel sentence structure.

gribozavr · 2025-12-05T21:01:02Z

src/idiomatic/foundations-api-design/predictable-api.md

+Keep your APIs predictable through naming conventions and implementing common
+traits.
+
+<!-- TODO -->


Some speaker notes would be nice. What is the framing for this section?

gribozavr

(misclick, I meant to simply "comment", but clicked "approve"; for clarity switching to "request changes")

gribozavr · 2025-12-07T00:53:13Z

src/idiomatic/foundations-api-design/predictable-api/naming-conventions.md

+# Naming Conventions
+
+<details>
+- One core component of readability and predictability is the way function names are composed.


Suggested change

- One core component of readability and predictability is the way function names are composed.

- One core component of API readability and predictability is the way function names are composed.

gribozavr · 2025-12-07T00:55:00Z

src/idiomatic/foundations-api-design/predictable-api/naming-conventions.md

+Rust's community developed naming conventions early, making them mostly
+consistent in places like the standard library.
+
+- Here we'll learn common components of rust method names, giving examples from


Suggested change

- Here we'll learn common components of rust method names, giving examples from

- In this section we'll learn common components of Rust method names, giving examples from

gribozavr · 2025-12-07T00:55:39Z

src/idiomatic/foundations-api-design/predictable-api/naming-conventions.md

+like a domain-specific language and quickly understand the functionality and use
+cases of a method.
+
+Rust's community developed naming conventions early, making them mostly


Suggested change

Rust's community developed naming conventions early, making them mostly

- Rust community developed naming conventions early, making them mostly

gribozavr · 2025-12-07T00:56:15Z

src/idiomatic/foundations-api-design/predictable-api/naming-conventions.md

+<details>
+- One core component of readability and predictability is the way function names are composed.
+
+A formal and consistently-applied naming convention lets developers treat names


Suggested change

A formal and consistently-applied naming convention lets developers treat names

- Formal and consistently-applied naming conventions let developers treat names

gribozavr · 2025-12-07T14:04:16Z

src/idiomatic/foundations-api-design/predictable-api/naming-conventions/01-get.md

@@ -0,0 +1,31 @@
+---
+minutes: 2
+---


These are great slides about naming conventions, but I have a couple of comments. I have left the comments on the "get" and "push" slides, but please apply them everywhere. All slides in this section should follow the same structure.

gribozavr · 2025-12-07T17:16:24Z

src/idiomatic/foundations-api-design/predictable-api/naming-conventions/13-as-and-ref.md

+<details>
+- Method for getting a reference-style value from an owned or borrowed value.
+
+- Often used for getting something internal to a type.


Suggested change

- Often used for getting something internal to a type.

- The type implementing an "as" method should contain one primary piece of data that is being borrowed out.

- The "as" naming convention does not work if the data type is an aggregate of many fields without an obvious primary one. Think about the call site:

```rust

my_vec.as_ptr() // OK

my_person.as_first_name() // does not read right, don't use "as_"

my_person.first_name() // OK

```

- If you want to have two getters that you need to distinguish, one that returns first name by value, and another one that returns it by reference, use `_ref` suffix:

```rust

impl Person {

fn first_name(&self) -> String

fn first_name_ref() -> &str

fn first_name_mut() -> &mut String

}

```

"Something internal" is quite unspecific. Here's my attempt at making it concrete. The "as" pattern is not applicable in every case, we need to have a type that wraps one specific thing that is being borrowed out.

Given the number of code examples, could you make a separate slide for this point that has all the necessary code snippets on the slide?

gribozavr · 2025-12-07T17:20:59Z

src/idiomatic/foundations-api-design/predictable-api/naming-conventions/14-mini-exercise.md

+Slice::get // ?
+Slice::get_unchecked_mut // ?


Suggested change

Slice::get // ?

Slice::get_unchecked_mut // ?

slice::get // ?

slice::get_unchecked_mut // ?

gribozavr · 2025-12-07T17:21:15Z

src/idiomatic/foundations-api-design/predictable-api/naming-conventions/14-mini-exercise.md

+2. What should we name these signatures?
+
+```rust,compile_fail
+// What are the types for these methods?


Suggested change

// What are the types for these methods?

// What are the types of these methods?

gribozavr · 2025-12-07T17:28:02Z

src/idiomatic/foundations-api-design/predictable-api/naming-conventions/14-mini-exercise.md

+Option::is_some // ?
+Slice::get // ?
+Slice::get_unchecked_mut // ?
+Option::as_ref // ?


Suggested change

Option::as_ref // ?

Option::as_ref // ?

str::from_utf8_unchecked_mut // ?

Rc::get_mut // ?

Vec::dedup_by_key // ?

gribozavr · 2025-12-07T17:28:46Z

src/idiomatic/foundations-api-design/predictable-api/naming-conventions/14-mini-exercise.md

+  types of the functions should be.
+
+- Go through the unnamed methods and brainstorm what names those methods should
+  have.


Please add expected answers to the speaker notes (for both Qs).

gribozavr · 2025-12-07T17:41:15Z

src/idiomatic/foundations-api-design/predictable-api/naming-conventions/06-with.md

+PathBuf::with_extension
+PathBuf::with_file_name


These two methods are actually defined on Path (they are callable through PathBuf because PathBuf: Deref<Target=Path>)

gribozavr · 2025-12-07T17:44:17Z

src/idiomatic/foundations-api-design/predictable-api/naming-conventions/08-into.md

@@ -0,0 +1,29 @@
+---
+Minutes: 2


Suggested change

Minutes: 2

minutes: 2

src/SUMMARY.md

gribozavr · 2025-12-07T17:47:13Z

src/idiomatic/foundations-api-design/predictable-api/naming-conventions/12-to.md

+Prefix to a function that takes a borrowed value and creates an owned value
+
+```rust
+String::to_owned // &str -> String (&str is not consumed)


Suggested change

String::to_owned // &str -> String (&str is not consumed)

str::to_owned // &str -> String (&str is not consumed)

gribozavr · 2025-12-07T17:47:43Z

src/idiomatic/foundations-api-design/predictable-api/naming-conventions/14-mini-exercise.md

+minutes: 10
+---
+
+Mini-exercise


Suggested change

Mini-exercise

# Exercise

gribozavr · 2025-12-07T17:48:00Z

src/idiomatic/foundations-api-design/predictable-api/naming-conventions/14-mini-exercise.md

+minutes: 10
+---
+
+Mini-exercise


Please rename the file as well to remove "mini".

Bring in existing foundations of API design work from google doc

9c1d7d1

tall-vase added the deep_dives/idiomatic label Dec 5, 2025

gribozavr approved these changes Dec 5, 2025

View reviewed changes

gribozavr requested changes Dec 5, 2025

View reviewed changes

gribozavr reviewed Dec 7, 2025

View reviewed changes

		Function names and type signatures already document some information, avoid
		repeating them!

	Function names and type signatures already document some information, avoid
	repeating them!
	Names and type signatures communicate a lot of information, don't repeat it in comments!

	- Motivation: Documentation that repeats name/signature information provides nothing new to the API user.
	- Motivation: Documentation that merely repeats name/signature information provides nothing new to the API user.

-- Motivation: It can be easy to fall into a pattern of writing only for you, but most documentation is for people coming in with a different perspective.
+- Background: The [curse of knowledge](https://en.wikipedia.org/wiki/Curse_of_knowledge) is a cognitive bias where experts assume that others have the same level of expertise and perspective.
+- Motivation: Your reader does not have the same level of expertise and the same perspective as you. Don't write for people like yourself, write for others.


		# Predictable API

		Keep your APIs predictable through naming conventions and implementing common

	Keep your APIs predictable through naming conventions and implementing common
	Keep your APIs predictable by following naming conventions and implementing common

	- One core component of readability and predictability is the way function names are composed.
	- One core component of API readability and predictability is the way function names are composed.

	- Here we'll learn common components of rust method names, giving examples from
	- In this section we'll learn common components of Rust method names, giving examples from

	Rust's community developed naming conventions early, making them mostly
	- Rust community developed naming conventions early, making them mostly

	A formal and consistently-applied naming convention lets developers treat names
	- Formal and consistently-applied naming conventions let developers treat names

		PathBuf::with_extension
		PathBuf::with_file_name

-- Often used for getting something internal to a type.
+- The type implementing an "as" method should contain one primary piece of data that is being borrowed out.
+  - The "as" naming convention does not work if the data type is an aggregate of many fields without an obvious primary one. Think about the call site:
+  ```rust
+  my_vec.as_ptr() // OK
+  my_person.as_first_name() // does not read right, don't use "as_"
+  my_person.first_name() // OK
+  ```
+  - If you want to have two getters that you need to distinguish, one that returns first name by value, and another one that returns it by reference, use `_ref` suffix:
+  ```rust
+  impl Person {
+    fn first_name(&self) -> String
+    fn first_name_ref() -> &str
+    fn first_name_mut() -> &mut String
+  }
+  ```

	// What are the types for these methods?
	// What are the types of these methods?

-Option::as_ref // ?
+Option::as_ref // ?
+str::from_utf8_unchecked_mut // ?
+Rc::get_mut // ?
+Vec::dedup_by_key // ?

	String::to_owned // &str -> String (&str is not consumed)
	str::to_owned // &str -> String (&str is not consumed)

Foundations of API Design chapter #2994

Are you sure you want to change the base?

Foundations of API Design chapter #2994

Uh oh!

Conversation

tall-vase commented Dec 5, 2025

Uh oh!

gribozavr commented Dec 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gribozavr left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

gribozavr commented Dec 5, 2025 •

edited

Loading