fun Kotlin.fact()

Fact #3: Markdown in documenting comments

2021-07-22T12:23:12+00:00

TL;DR: Where Java uses verbose HTML markup, in Kotlin you can use Markdown.

Kotlin uses KDoc to document the code. It’s not an extension of Javadoc, but not by accident it’s similar to it. However, Kotlin designers decided to go another way for certain features.

Let’s take a look at an example Javadoc:

/**
 * Here I'm going to list some <b>important things</b> to know when calling this function:
 * <ul>
 * <li>first item</li>
 * <li>second item - look at <a href="example.com">this link</a></li>
 * <li>third item</li>
 * </ul>
 *
 * Paragraph 2
 * <br>
 * Paragraph 3
 */
public void someImportantFunction() {

HTML looks a big clunky these days, right? It certainly adds some noise - extra effort when both writing and reading it. It wasn’t really designed to be readable as code, in contrast to Markdown.

Converting the above to Kotlin gives us:

/**
 * Here I'm going to list some **important things** to know when calling this function:
 *
 *  * first item
 *  * second item - look at [this link](example.com)
 *  * third item
 *
 * Paragraph 2
 *
 * Paragraph 3
 */
fun someImportantFunction() {

Looks simpler, right?

You may say that some modern IDEs actually render the documenting comments. It’s true:

However, not all tools do it. For example, during code review, or simply browsing on GitHub or BitBucket. Editing the comment in a WYSIWYG manner is also in theory possible, but since most of us already got used to Markdown, we can use it as well and appreciate KDoc for this improvement.

Fact #2: Easy migration from deprecated APIs

2021-05-17T07:18:12+00:00

TL;DR: Alt+Enter is your friend when moving away from deprecated APIs in Kotlin.

Deprecations happen when library authors come up with a better way to handle a specific use case. It often saves library maintainers’ time because of no further need to support the old API, but creates an extra overhead for library consumers because they need to migrate their code.

Kotlin has a nice little feature that facilitates this process. For example, the recent deprecations around Time API resulted in such warning when switching to Kotlin 1.5.0:

The clue is that together with the deprecation notice, IntelliJ offers an action to replace with the new recommended API. This is possible thanks to the extra piece of info in the @Deprecated annotation:

@Deprecated(
    "Use lowercase() instead.",
    ReplaceWith("lowercase(Locale.getDefault())", "java.util.Locale"))

where ReplaceWith is defined like this:

/**
* Specifies a code fragment that can be used to replace a deprecated function, property or class. Tools such
* as IDEs can automatically apply the replacements specified through this annotation.
*
* @property expression the replacement expression. The replacement expression is interpreted in the context
*     of the symbol being used, and can reference members of enclosing classes etc.
*     For function calls, the replacement expression may contain argument names of the deprecated function,
*     which will be substituted with actual parameters used in the call being updated. The imports used in the file
*     containing the deprecated function or property are NOT accessible; if the replacement expression refers
*     on any of those imports, they need to be specified explicitly in the [imports] parameter.
* @property imports the qualified names that need to be imported in order for the references in the
*     replacement expression to be resolved correctly.
*/
@Target()
@Retention(BINARY)
@MustBeDocumented
public annotation class ReplaceWith(val expression: String, vararg val imports: String)

It’s helpful for both sides of the library API: author and consumer. IntelliJ doesn’t have monopoly to suggest such replacements - it can ba used by any tool, maybe ktlint or detekt in the future.

Fact #1: Stand-alone scripts

2021-05-06T08:49:47+00:00

TL;DR: Kotlin is a good fit for everyday scripting, as a type-safe replacement for bash or Python.

Did you know that Kotlin supports stand-alone scripts (files with .main.kts extension), with proper IntelliJ support? Some time ago one had to use an external library kscript to make it possible, but with release of Kotlin 1.4.0 it seems like JetBrains got it even further than kscript. For me it’s perfect for any kind of everyday scripting that is beyond simple shell one-liners.

For example, I wanted to have a script that get rids of local git branches that have been already gone from the remote. Git lacks built-in local branch pruning (like git fetch -p for remote ones), and such bash-based solutions are cumbersome to write and crash whenever git prints something that is not a list of branches, unless you handle it explicitly. I used a Groovy library grgit (a Groovy wrapper for JGit, unfortunately no longer maintained, but still usable) to have an object-based access to git. See krzema12/PersonalConfigs/…/removeLocalMergedBranches.main.kts. Shebang makes executing it as easy as calling removeLocalMergedBranches.main.kts if it’s in your PATH, from your git repo.

Demo: