update: improve Classes page #4786

AlejandraPedroza · 2025-04-02T14:13:02Z

This PR revamps the content and code examples in the Classes page following external feedback.
Some of the key changes are:

Improve the whole page and revamp the code snippets.
Explain the use case for multiple init blocks.
Explain constructor chaining.
Add examples for primary constructors.
Clarify the open keyword.
Explain how to access a class property from a class member function.
Use the term "object" consistently.
Clarify what abstract classes are.
Provide example companion objects.

ice-phoenix

My main question is: what are the things we want the reader to know, after they've finished reading the updated "Classes" page? Is it basic syntax for classes, details about constructors, details about initialization, smth else? Right now the section is a bit all over the place, I feel.

In other words, when we set to improve the page, what did we want to achieve?

docs/topics/classes.md

ice-phoenix

Thanks for the updates! In general, I like the new version.

I narrowed down my main concern to the struggle between "being succinct and to the point targeting existing developers" in the old version vs "being very detailed and explaining very basic things targeting novice developers" in the new one. I don't know how to find a good balance here besides taking a look at the actual feedback of users and what they are missing.

Additionally, I think it's important to remember that, while all and every feedback is important, a lot of people who were completely satisfied with the current succinct and to-the-point version didn't leave their positive feedback. We might "over-optimize" for the smaller part of our target audience which is more vocal and more novice, and they want very basic things explained in detail.

Note: feel free to disregard my general feedback and only incorporate the technical notes, as you are the person who definitely knows more about how to write good technical documentation. If you believe it should be done in a specific way, then that's what we should do.

docs/topics/inheritance.md

docs/topics/classes.md

github-actions · 2025-05-31T00:00:33Z

This PR is stale because it has been open 30 days with no activity. Remove stale label or comment or this will be closed in 7 days.

github-actions · 2025-07-01T00:00:30Z

This PR is stale because it has been open 30 days with no activity. Remove stale label or comment or this will be closed in 7 days.

AlejandraPedroza · 2025-08-18T10:57:05Z

@ice-phoenix

Thanks for your detailed review!
The aim is to make the content more accessible and useful for both groups. Better examples and explanations will help beginners progress to the intermediate level and help experienced developers solve typical problems.
Also, when improving pages, we prioritize practical, widely useful information. We take user feedback into account, but assess very specific cases with low impact. Based on this approach, we work with SMEs to balance what and how we document: tech writers as content experts, SMEs as technical experts.
I appreciate your technical suggestions. I applied them overall.
From the content side, I reviewed why the page felt over-documented, and produced a clearer, more concise version.

ice-phoenix

Thank you for the update, it looks much more focused and to the point, compared to the previous version! I've left some comments, but overall I don't have a lot to add.

In all the places where we are technically not entirely correct, we are ambiguous enough and pragmatic enough; to fix these places, we would need to introduce too many additional things and details, which is not really appropriate for this page, I feel.

docs/topics/classes.md

ice-phoenix

:lgtm:

sarahhaggarty

Huge effort Ale! 🚀 It's definitely looking much better than the original. Thanks for the hard work!
Please take a look at my suggestions.
There's some for improving names in code samples as well as adding code comments for printed statements within the main() function of samples.
I made a couple minor structural suggestions and asked a couple of questions for clarification.

sarahhaggarty · 2025-08-25T10:11:23Z

docs/topics/classes.md

+When you [create an instance of a class](#creating-instances-of-classes), you are creating 
+a concrete object based on that blueprint.
+
+Kotlin offers a concise syntax for declaring classes. To declare a class, use the `class` keyword 


Suggested change

Kotlin offers a concise syntax for declaring classes. To declare a class, use the `class` keyword

Kotlin offers concise syntax for declaring classes. To declare a class, use the `class` keyword

sarahhaggarty · 2025-08-25T10:12:00Z

docs/topics/classes.md

+  * [Nested and inner classes](nested-classes.md)
+  * [Object declarations](object-declarations.md)
+
+Both the class header and class body can be minimal. 


What do you mean by "minimal" here?

sarahhaggarty · 2025-08-25T10:12:12Z

docs/topics/classes.md

+  * [Object declarations](object-declarations.md)
+
+Both the class header and class body can be minimal. 
+If the class does not have a body, you can omit the curly braces `{}`:


Suggested change

If the class does not have a body, you can omit the curly braces `{}`:

If the class doesn't have a body, you can omit the curly braces `{}`:

sarahhaggarty · 2025-08-25T10:13:24Z

docs/topics/classes.md

-is declared in the class header, and it goes after the class name and optional type parameters.
+```kotlin
+// Person class with a primary constructor 
+// that nitializes the name property


Suggested change

// that nitializes the name property

// that initializes the name property

sarahhaggarty · 2025-08-25T10:22:04Z

docs/topics/classes.md

 ```

-## Constructors
+Here's an example of a class with a header, body, and an [instance created](#creating-instances-of-classes) from it:


Suggested change

Here's an example of a class with a header, body, and an [instance created](#creating-instances-of-classes) from it:

Here's an example that declares a class with a header and body, then [creates an instance](#creating-instances-of-classes) from it:

This doesn't sound natural to me. I've suggested an alternative. I think it's because the "class with a header and body" is the important part. It separates it from the instance creation which is a different level of abstraction.

sarahhaggarty · 2025-08-27T09:14:30Z

docs/topics/classes.md

 }
 ```
 {kotlin-runnable="true"}

-If a non-abstract class does not declare any constructors (primary or secondary), it will have a generated primary constructor
-with no arguments. The visibility of the constructor will be public.
+If there's a class that does not declare any constructors (primary or secondary), it will have an implicit primary constructor


I think it would be good to put the rest of this content under a separate header. It doesn't really fit under "Secondary constructors". Maybe "Without constructors"?

sarahhaggarty · 2025-08-27T09:16:27Z

docs/topics/classes.md

+
+fun main() {
+    // Creates an instance of the Person class
+    Person("John", 30)


Suggested change

Person("John", 30)

Person("John", 30)

// Person created: John, age 30.

sarahhaggarty · 2025-08-27T09:17:24Z

docs/topics/classes.md

+    // and converts it to an integer
+    constructor(name: String, age: String) : this(name, age.toIntOrNull() ?: 0) {
+        println("$name created with converted age: $age")
+        // Bob created with converted age: 8


Suggested change

// Bob created with converted age: 8

sarahhaggarty · 2025-08-27T09:17:36Z

docs/topics/classes.md

+
+fun main() {
+    // Uses the secondary constructor with a String age
+    Person("Bob", "8")


Suggested change

Person("Bob", "8")

Person("Bob", "8")

// Bob created with converted age: 8

I think it makes more sense to add the printed statement here for the constructor.

sarahhaggarty · 2025-08-27T09:18:53Z

docs/topics/classes.md

+    // to the primary constructor
+    constructor(name: String) : this(name, 0) {
+        println("Person created with default age: $age and name: $name.")
+        // Person created with default age: 0 and name: Alice.


Can you move the code comments to where they will appear when triggered by the main function?

AlejandraPedroza requested a review from a team as a code owner April 2, 2025 14:13

AlejandraPedroza requested a review from ice-phoenix April 2, 2025 14:13

AlejandraPedroza force-pushed the update-classes-page branch from b4d1916 to 85c4e7f Compare April 7, 2025 08:54

ice-phoenix requested changes Apr 7, 2025

View reviewed changes

AlejandraPedroza force-pushed the update-classes-page branch from 82db250 to 9fb5f07 Compare April 14, 2025 13:09

AlejandraPedroza force-pushed the update-classes-page branch from 3ce95e1 to 3871cf7 Compare April 23, 2025 12:37

ice-phoenix requested changes Apr 29, 2025

View reviewed changes

github-actions bot added the Stale label May 31, 2025

koshachy removed the Stale label May 31, 2025

github-actions bot added the Stale label Jul 1, 2025

AlejandraPedroza removed the Stale label Jul 1, 2025

AlejandraPedroza marked this pull request as draft July 1, 2025 08:35

AlejandraPedroza force-pushed the update-classes-page branch from 3871cf7 to e809a7e Compare August 12, 2025 14:45

AlejandraPedroza requested a review from ice-phoenix August 18, 2025 10:57

AlejandraPedroza force-pushed the update-classes-page branch from 80f3e37 to aa0edf2 Compare August 19, 2025 13:55

AlejandraPedroza marked this pull request as ready for review August 19, 2025 14:55

ice-phoenix requested changes Aug 19, 2025

View reviewed changes

AlejandraPedroza added 5 commits August 20, 2025 12:16

update: improve Classes page

12b7501

chore: fix anchors

4e97339

Marat review

6b2fb0b

Review second round

33b0bad

SME review

e3e1830

AlejandraPedroza force-pushed the update-classes-page branch from 132ed5c to e3e1830 Compare August 20, 2025 10:16

ice-phoenix approved these changes Aug 20, 2025

View reviewed changes

sarahhaggarty self-assigned this Aug 20, 2025

sarahhaggarty requested changes Aug 27, 2025

View reviewed changes

	Kotlin offers a concise syntax for declaring classes. To declare a class, use the `class` keyword
	Kotlin offers concise syntax for declaring classes. To declare a class, use the `class` keyword

	If the class does not have a body, you can omit the curly braces `{}`:
	If the class doesn't have a body, you can omit the curly braces `{}`:

	// that nitializes the name property
	// that initializes the name property

	Here's an example of a class with a header, body, and an [instance created](#creating-instances-of-classes) from it:
	Here's an example that declares a class with a header and body, then [creates an instance](#creating-instances-of-classes) from it:

	Person("John", 30)
	Person("John", 30)
	// Person created: John, age 30.

	Person("Bob", "8")
	Person("Bob", "8")
	// Bob created with converted age: 8

update: improve Classes page #4786

Are you sure you want to change the base?

update: improve Classes page #4786

Uh oh!

Conversation

AlejandraPedroza commented Apr 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ice-phoenix left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ice-phoenix left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actions bot commented May 31, 2025

Uh oh!

github-actions bot commented Jul 1, 2025

Uh oh!

AlejandraPedroza commented Aug 18, 2025

Uh oh!

ice-phoenix left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ice-phoenix left a comment

Choose a reason for hiding this comment

Uh oh!

sarahhaggarty 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!

Uh oh!

AlejandraPedroza commented Apr 2, 2025 •

edited

Loading