Kotlin code example standards

Kotlin SDK Standards Document

This document summarizes important points for writing and reviewing code examples written for the AWS SDK for Kotlin. For more information on tools and standards, see the complete list in TCX Code Examples Standards.

General Structure

Service folders with examples should follow the common structure that uses folders for Actions, Scenarios, and Tests, with a top level Gradle build file.

Code examples that use a Kotlin client should follow the Client Builder Pattern, which is a common design pattern used with Kotlin. In addition, the method that uses the Kotlin client has to be a suspend function that adheres to Kotlin coroutine functionality.

suspend fun createMap(mapName: String): String {
    val configuration = MapConfiguration {
        style = "VectorEsriNavigation"
    }

    val mapRequest = CreateMapRequest {
        this.mapName = mapName
        this.configuration = configuration
        description = "A map created using the Kotlin SDK"
    }

    LocationClient { region = "us-east-1" }.use  { client ->
        val response = client.createMap(mapRequest)
        return response.mapArn
    }
}

The use block is good when you know you need to run a block of code and then definitely close the client. If your code only ever executes a single call on a client then this style is appropriate. If you need to make multiple calls (for example, a Basics scenario where multiple operations are invoked), the this pattern would not be appropriate.

In this situation, you can declare a service client like.

val client = LocationClient.fromEnvironment { ... }

Using fromEnvironment is preferable to manual client construction.

Examples should use JDK 17+ and string interpolation ($repoName).

val instructions = """
1. Authenticate with ECR - Before you can pull the image from Amazon ECR, you need to authenticate with the registry. You can do this using the AWS CLI:

    aws ecr get-login-password --region us-east-1 | docker login --username AWS --password-stdin $accountId.dkr.ecr.us-east-1.amazonaws.com

2. Describe the image using this command:

   aws ecr describe-images --repository-name $repoName --image-ids imageTag=$localImageName

3. Run the Docker container and view the output using this command:

   docker run --rm $accountId.dkr.ecr.us-east-1.amazonaws.com/$repoName:$localImageName
"""

When a service is added or updated, update the Kotlin Github repo so it will be included in the build/lint/format and Weathertop tests.

We're creating explicit request objects (CreateMapRequest) and nested data (MapConfiguration) rather than using the full DSL syntax. This is pretty verbose and not what most Kotlin users will expect given how other Kotlin frameworks are built/documented. Examples should generally favor more concise, idiomatic invocations.

suspend fun createMap(mapName: String): String
    val response = locationClient.createMap {
        this.mapName = mapName
        description = "A map created using the Kotlin SDK"
        configuration {
            style = "VectorEsriNavigation"
        }
    }

    return response.mapArn
}

Import statements should not include any unused imports, wildcards, and be ordered alphabetically.

All Kotlin code examples should be lintered using ktlint 12.1.1 (or higher).

Tests must use @TestInstance and @TestMethodOrder JUNT annotations.

@TestInstance(TestInstance.Lifecycle.PER_CLASS)
@TestMethodOrder(MethodOrderer.OrderAnnotation::class)
class ECRTest {

Integration tests should be marked with @Order(1) for ordering tests and use runBlocking{}.

   @Test
    @Tag("IntegrationTest")
    @Order(1)
    fun testHello() =
        runBlocking {
            listImageTags(repoName)
            println("Test 2 passed")
        }

Use Gradle for dependency management.

Recommend keeping dependencies up-to-date and following best practices for dependency management. That is, every 3-4 months - update the Kotlin SDK build.

Metadata for Action examples should contain at minimum the following snippets.

• A snippet to show the action itself within context.
• If more than one variation of the Action is included, use descriptions in the metadata to explain the differences.

Metadata for scenario examples should contain the Action class and Scenario that contains the main() that contains the ouptu of the program.