Replace reference numbers with inline comments

[sampalmer]

Background

I'm brand new to Kotlin and working through Kotlin by Example. I've noticed that each topic is organised into a structure similar to the following:

package org.kotlinlang.play         // 1

fun main() {                        // 2
    println("Hello, World!")        // 3
}

1. Kotlin code is usually defined in packages. Package specification is optional: If you don't specify a package in a source file, its content goes to the default package.
2. An entry point to a Kotlin application is the main function. In Kotlin 1.3, you can declare main without any parameters. The return type is not specified, which means that the function returns nothing.
3. println writes a line to the standard output. It is imported implicitly. Also note that semicolons are optional.

Problem

Personally, I find this difficult to follow. For each line of code, I need to:

1. Read the line of code
2. Memorise the reference number at the end of the line
3. Skip down the page to the reference notes
4. Find the reference note with the memorised reference number
5. Read the reference note
6. Skip back up the page to the code
7. Find the line of code I was last at

By the time I finish the topic, I have skipped up and down the page several times.

Solution

Inline the reference notes into the code:

// Kotlin code is usually defined in packages.
// Package specification is optional: If you don't specify a package in a source file,
// its content goes to the default package.
package org.kotlinlang.play

// An entry point to a Kotlin application is the main function.
// In Kotlin 1.3, you can declare main without any parameters.
// The return type is not specified, which means that the function returns nothing.
fun main() {
    // println() writes a line to the standard output.
    // It is imported implicitly. Also note that semicolons are optional.
    println("Hello, World!")
}

Benefits

Now, instead of having to keep skipping down and up the page, I can just follow it from top to bottom. So for each line of code, I need to:

1. Read the comment
2. Read the line of code

I find this significantly easier to follow than the way it's currently done.

Alternative solution

If you don't like the look of detailed notes inside code comments, then you could interleave the notes with the code:

Kotlin code is usually defined in packages. Package specification is optional: If you don't specify a package in a source file, its content goes to the default package.

package org.kotlinlang.play

An entry point to a Kotlin application is the main function. In Kotlin 1.3, you can declare main without any parameters. The return type is not specified, which means that the function returns nothing.

fun main() {

println writes a line to the standard output. It is imported implicitly. Also note that semicolons are optional.

    println("Hello, World!")
}

This way is a bit nicer to read, but now it's hard to copy and run the full code block since it's split up, so I'm not sure if it's worth it.

Pull request

I'm happy to make the changes myself and submit a pull request.

[p7nov]

Hi!
Thanks for using Kotlin by Example and offering your help in improving it.
Your solution looks pretty neat; however, there are certain issues which are major for the current structure:

• The first solution significantly decreases the readability since there is no text formatting and all the text is grey. This would be good for reading in an IDE but on web pages, it lacks expressiveness.
• The alternative solution makes it impossible to run the entire code sample. We find this unsuitable for interactive learning as well.

So, we find the current design acceptable despite its drawbacks. It's widely used in documentation for other languages and programming learning resources.

Thanks again and good luck in learning Kotlin!
Feel free to contact us on GitHub or in Kotlin slack. BTW, there is a separate channel for Kotlin by Example.

Regards, Pavel,
Kotlin Technical Writer,
JetBrains