From 83ab19a962637259d81cc44bad931a051064fb52 Mon Sep 17 00:00:00 2001 From: Colin Leach Date: Fri, 29 Aug 2025 11:23:26 -0700 Subject: [PATCH 1/7] Replace `basics/about.md` with longer version --- concepts/basics/about.md | 117 ++++++++++++++++++++++++++++++++------- 1 file changed, 97 insertions(+), 20 deletions(-) diff --git a/concepts/basics/about.md b/concepts/basics/about.md index 2a068cbd..c7b041ef 100644 --- a/concepts/basics/about.md +++ b/concepts/basics/about.md @@ -1,41 +1,118 @@ -# About +# About Basics -## Type inference +Kotlin is a statically typed language, designed to be fully interoperable with Java. -Kotlin compiler can infer types for functions and variables in most of the cases. However, declaring function return types explicitly for **public API** is a good practice. +Distinguishing it from Java, Kotlin: -## Entry point +- has a cleaner, more concise syntax; +- incorporates many features of functional languages; +- has extensive support for nullable values. -To run your Kotlin program you need to define so-called entry point: top-level function with name `main` with or without arguments. However, in Exercism course we are using automatic tests that are using other functions defined in exercises. +## Variables -Entry point with arguments (you can use them for building CLI applications): +Because Kotlin is statically typed, it is necessary to _know_ the type of each value at compile time. + +However, Kotlin's [type inference][inference] is very powerful, so _specifying_ the type is often optional. + +There are two ways to declare a variable. + +1. `val` creates an immutable variable, and trying to change it is a compile-time error. ```kotlin -fun main(args: Array) { - println("Hello, Exercism!") - println("Program args are: $args") -} +val x = 42 // => 42 +x = 43 // => 'val' cannot be reasssigned ``` -Or ignore arguments completely: +2. `var` creates a mutable variable. + +```Kotlin +var x = 42 // => 42 +x = 43 // => 43 +``` + +Because immutable variables eliminate a common class of bugs, use of `val` is encouraged whenever possible. + +To reduce visual distraction, explicit types will mostly be omitted from this syllabus. +Nevertheless, it is recommended to specify types in all serious code (for safety, and for documentation). ```kotlin -fun main() { - println("Hello, Exercism!") +val x: Int = 42 // => 42 +``` + +In general, the names of variables and functions should be in camelCase, not snake_case + +## Functions + +Declare a function with the `fun` keyword. +Unlike Java, functions are not required to be part of a class. + +```Kotlin +fun hello(): String { + return "Hello, World!" +} + +fun add(x: Int, y: Int): Int { + return x + y } ``` -## `Unit` return type +Some points to note: + +- Parentheses `()` are needed after the function name, even if the function takes no arguments. +- Function arguments need to specify the type: there is no type inference (in contract to variables). +- The body of the function is enclosed in braces `{ }` (though see below). +- The `return` keyword is required, if returning a value. +- Semicolons `;` at the end of lines are optional, and usually omitted. +- Arithmetic operators `+`, `-`, `*`, `/` are similar to most mainstream languages. -You've seen that some functions (like `main()` above) are not returning value. However, they are implicitly returning value that is called `Unit` (quite similar to `void` in Java/C/C++): +However, for these very simple, "single-expression" functions, there is an abbreviated syntax: + +```Kotlin +// return type is usually omitted for single-expression functions +fun add(x: Int, y: Int) = x + y +``` +Functions can have parameters with default values. +These values will be used if they are omitted where the function is invoked: ```kotlin -fun run() {} +fun ping(host: String = "localhost") { + println("PING --> $host") +} -// is the same as -fun run(): Unit { return Unit } +ping("exercism.io") // PING --> exercism.io +ping() // PING --> localhost ``` -Returning `Unit` (and using it in function declaration) is completely optional and is omitted in most of the cases. +Functions within Exercism will usually return a value (because of the way the test runner is structured). +To use Kotlin more widely, it may be useful to know that a function which returns no value can omit the return type and the return keyword. + +It is then said to have a `Unit` return type: equivalent to `void` in Java and several other languages. + +## Comments + +Single-line comments start with `//`, and the rest of the line is then ignored. + +Multi-line comments start with `/*` and end with `*/` + +```Kotlin +fun hello(): String { + /* + * Failing to run this program on a new installation + * is considered bad luck + */ + return "Hello, World!" // the compiler pixies are now happy +} +``` + +This is the same as Java. + +~~~~exercism-note +Because of the importance of Java interop, many Kotlin learners are at least somewhat familiar with Java. + +We will try to point out similarities and differences between the languages throughout the syllabus. + +_Please ignore this if you are a Kotlin-first learner!_ +~~~~ + -[intellij-idea-ic]: https://www.jetbrains.com/idea/download/ +[inference]: https://en.wikipedia.org/wiki/Type_inference From 1c6f4e55f63452d2602b454555f8f375f5ad4ce2 Mon Sep 17 00:00:00 2001 From: Colin Leach Date: Fri, 29 Aug 2025 11:27:24 -0700 Subject: [PATCH 2/7] fix typo --- concepts/basics/about.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/concepts/basics/about.md b/concepts/basics/about.md index c7b041ef..66cd7c78 100644 --- a/concepts/basics/about.md +++ b/concepts/basics/about.md @@ -59,7 +59,7 @@ fun add(x: Int, y: Int): Int { Some points to note: - Parentheses `()` are needed after the function name, even if the function takes no arguments. -- Function arguments need to specify the type: there is no type inference (in contract to variables). +- Function arguments need to specify the type: there is no type inference (in contrast to variables). - The body of the function is enclosed in braces `{ }` (though see below). - The `return` keyword is required, if returning a value. - Semicolons `;` at the end of lines are optional, and usually omitted. From be681f3577a3315f14dff02e17c87ef006a9c4fd Mon Sep 17 00:00:00 2001 From: Colin Leach Date: Fri, 29 Aug 2025 14:26:09 -0700 Subject: [PATCH 3/7] Update concepts/basics/about.md Co-authored-by: Derk-Jan Karrenbeld --- concepts/basics/about.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/concepts/basics/about.md b/concepts/basics/about.md index 66cd7c78..0e46fff2 100644 --- a/concepts/basics/about.md +++ b/concepts/basics/about.md @@ -33,7 +33,13 @@ x = 43 // => 43 Because immutable variables eliminate a common class of bugs, use of `val` is encouraged whenever possible. To reduce visual distraction, explicit types will mostly be omitted from this syllabus. -Nevertheless, it is recommended to specify types in all serious code (for safety, and for documentation). +Nevertheless, it is recommended to specify types at least for: + +- for public APIs +- function signatures +- where it needs documentation + +Some companies and organisations will require strict type safety and disallow type inference, whilst others restrict it to "simple" types, or embrace type inference fully. ```kotlin val x: Int = 42 // => 42 From 7b9dc63bf0507245924479697eab2048364cd28e Mon Sep 17 00:00:00 2001 From: Colin Leach Date: Fri, 29 Aug 2025 14:26:24 -0700 Subject: [PATCH 4/7] Update concepts/basics/about.md Co-authored-by: Derk-Jan Karrenbeld --- concepts/basics/about.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/concepts/basics/about.md b/concepts/basics/about.md index 0e46fff2..4bcd95f9 100644 --- a/concepts/basics/about.md +++ b/concepts/basics/about.md @@ -45,7 +45,7 @@ Some companies and organisations will require strict type safety and disallow ty val x: Int = 42 // => 42 ``` -In general, the names of variables and functions should be in camelCase, not snake_case +In general, the names of variables and functions should be in `camelCase`, not `snake_case` ## Functions From 006cfbbf01c40df18234c40a14b1deb40bceaf9e Mon Sep 17 00:00:00 2001 From: Colin Leach Date: Fri, 29 Aug 2025 14:28:51 -0700 Subject: [PATCH 5/7] Update concepts/basics/about.md Co-authored-by: Derk-Jan Karrenbeld --- concepts/basics/about.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/concepts/basics/about.md b/concepts/basics/about.md index 4bcd95f9..4a686947 100644 --- a/concepts/basics/about.md +++ b/concepts/basics/about.md @@ -112,7 +112,7 @@ fun hello(): String { This is the same as Java. -~~~~exercism-note +~~~~exercism/note Because of the importance of Java interop, many Kotlin learners are at least somewhat familiar with Java. We will try to point out similarities and differences between the languages throughout the syllabus. From 3137d9f71370f04f1e2b0728e43c920f8e55e5c4 Mon Sep 17 00:00:00 2001 From: Colin Leach Date: Fri, 29 Aug 2025 14:35:14 -0700 Subject: [PATCH 6/7] Clarify type restrictions for 'var' in Kotlin Added a few extra lines. --- concepts/basics/about.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/concepts/basics/about.md b/concepts/basics/about.md index 4a686947..f75f5529 100644 --- a/concepts/basics/about.md +++ b/concepts/basics/about.md @@ -32,6 +32,13 @@ x = 43 // => 43 Because immutable variables eliminate a common class of bugs, use of `val` is encouraged whenever possible. +Also, even a `var` cannot change type: + +```kotlin +var x = 42 +x = "foobar" // => Type mismatch: inferred type is String but Int was expected +``` + To reduce visual distraction, explicit types will mostly be omitted from this syllabus. Nevertheless, it is recommended to specify types at least for: From 7cea1e71cc6a9669cb8667220c67c20e6e77d980 Mon Sep 17 00:00:00 2001 From: Colin Leach Date: Fri, 29 Aug 2025 14:36:37 -0700 Subject: [PATCH 7/7] Fix formatting in about.md for clarity removed double "for" --- concepts/basics/about.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/concepts/basics/about.md b/concepts/basics/about.md index f75f5529..2dc8580c 100644 --- a/concepts/basics/about.md +++ b/concepts/basics/about.md @@ -42,7 +42,7 @@ x = "foobar" // => Type mismatch: inferred type is String but Int was expected To reduce visual distraction, explicit types will mostly be omitted from this syllabus. Nevertheless, it is recommended to specify types at least for: -- for public APIs +- public APIs - function signatures - where it needs documentation