Android Java to Kotlin Conversion (Second Pass)
The IDE converter produces Kotlin that compiles but is not idiomatic: platform types
everywhere, one giant function per lifecycle callback, nested if/else, new Thread,
switch, TextUtils.isEmpty, magic numbers. This skill drives the disciplined second
pass that turns that output into clean, modern, testable Kotlin — without changing
observable behaviour — and then writes a test that proves behaviour is unchanged.
The Two-Person Workflow
This skill assumes a hand-off:
Developer runs the mechanical IDE conversion (Code > Convert Java File to Kotlin File, or ⌥⇧⌘K), producing a .kt file that compiles but is not idiomatic.
You (Claude) drive everything after that:
Step 0 Baseline → Step 1 Idiomatic pass → Step 2 Behaviour-locking test → Step 3
Verify. If Step 3 fails or behaviour drifts, loop back to Step 1.
If you are handed a .java file instead, first apply a faithful 1:1 translation to reach
the same starting point, then continue.
The Prime Directive: Behaviour Must Not Change
Every transformation in this skill is behaviour-preserving. You are refactoring for
readability, safety, and modern API usage — not adding features or fixing bugs. If you
spot a real bug, surface it to the developer; do not silently "fix" it inside a
conversion. The behaviour-locking test in Step 3 exists to keep you honest.
Step 0: Establish Baseline
Before editing anything:
- Read the whole
.kt file (and, if you can, the original .java via
git show <rev>:<path>.java or the IDE's local history) to understand what it does.
- Write down the public/observable surface you must keep intact:
- Lifecycle callbacks (
onCreate, onViewCreated, onSaveInstanceState, …) and their
ordering of side-effects.
- Any Parcelable/Bundle keys, intent extras, and
newInstance(...) factory shapes.
- Note threading: which work runs off the main thread today (
Thread, AsyncTask,
runOnUiThread, executors) — this maps to coroutines in Step 2.
Step 1: Idiomatic Pass
Apply, in this order, then re-check the invariants:
- Kill platform types. Give every
! platform type an explicit nullable/non-null
type based on the Java source and call sites.
- Fail fast. Replace nested
if/else pyramids and null-checks with guard clauses
and require/requireNotNull/?: return. See FAIL-FAST.md.
- Decompose. Break each oversized lifecycle callback /
setupView-style method into
small, single-purpose private functions named for their intent. See
ANDROID-IDIOMS.md.
- Modern concurrency. Replace
new Thread, AsyncTask, runOnUiThread, and
callback pairs with lifecycleScope + suspend + withContext. See
CONCURRENCY.md.
- Modern Android + Kotlin idioms. Scope functions (
run/apply/let), extension
functions, when/partition/filter over switch, string templates, isNullOrEmpty,
view/KTX extensions. See ANDROID-IDIOMS.md. Retire
deprecated Android APIs (onActivityResult, options-menu overrides,
java.util.Observable) — see DEPRECATED-APIS.md.
- Project conventions. SPDX header, no magic numbers (
companion object +
const val), resources not hardcoded strings, ≤300 lines/file, ≤120 cols. See
PROJECT-CONVENTIONS.md.
- Testability seams. Extract pure logic (URL building, permission math, partitioning)
into functions you can unit-test; mark with
@VisibleForTesting where they must stay
internal/private-ish but be reachable from tests.
Do NOT expand scope. Unrelated files stay untouched (AGENTS.md / AI policy).
Step 2: Write a Behaviour-Locking Test (Mandatory)
A conversion is not complete until a test proves behaviour is unchanged. See
TESTING.md for the decision tree. In short:
- Pure functions you extracted (e.g. link builders,
isReshareForbidden,
partitioning) → fast JVM unit tests in app/src/test/ (JUnit4 + mockito-kotlin).
- Fragment/Activity/DB behaviour → instrumented test in
app/src/androidTest/
extending the project's base test class, or a Robolectric test where the project uses it.
- Prefer testing the seams you just created. If the Java original had no test, your
new test is the characterization test that locks current behaviour.
Every test file gets the SPDX header and follows the project's test conventions.
Step 3: Verify
Run and report real output — never claim green without evidence:
# Formatting + static analysis on the changed files
./gradlew spotlessKotlinCheck detektGplayDebug lintGplayDebug spotbugsGplayDebug
# Unit tests
./gradlew jacocoTestGplayDebugUnitTest
# Instrumented tests (if you wrote one), scoped to the class
./gradlew createGplayDebugCoverageReport -Pcoverage=true \
-Pandroid.testInstrumentationRunnerArguments.class=<fully.qualified.TestClass>
Worked Example
assets/worked-example.md is a real before/after from
FileDetailSharingFragment (871-line Java fragment → idiomatic Kotlin) showing each
transformation class in context. Read it when you need a concrete pattern.
Batch Conversion
Convert one file at a time, leaf dependencies first. Report progress per file. Warn the
developer before a change set grows into several thousand lines — split into focused PRs
(AGENTS.md). Each commit needs Assisted-by: <agent>:<model>; only the human adds
Signed-off-by.
1---2name: android-java-to-kotlin3description: >4 Use when finishing a Java-to-Kotlin conversion in an Android project, when the user5 mentions "java to kotlin", "j2k", "convert java", "migrate java to kotlin", "finish the6 conversion", "make it idiomatic", or when a freshly IDE-converted .kt file needs to be7 turned into clean, modern, idiomatic Kotlin. The developer first runs the IDE converter8 (Android Studio: Code > Convert Java File to Kotlin File), then this skill drives the9 second pass: idiomatic cleanup, fail-fast control flow, coroutines/lifecycleScope,10 modern Android APIs, function decomposition, and a behaviour-locking test.11license: AGPL-3.0-or-later12SPDX-FileCopyrightText: 2026 Nextcloud GmbH and Nextcloud contributors13SPDX-License-Identifier: AGPL-3.0-or-later14metadata:15 source: https://skillmd.com/skills/nextcloud/android-java-to-kotlin16 author: Nextcloud Android17 version: "1.0.0"18---1920# Android Java to Kotlin Conversion (Second Pass)2122The IDE converter produces Kotlin that *compiles* but is not *idiomatic*: platform types23everywhere, one giant function per lifecycle callback, nested `if`/`else`, `new Thread`,24`switch`, `TextUtils.isEmpty`, magic numbers. This skill drives the disciplined second25pass that turns that output into clean, modern, testable Kotlin — **without changing26observable behaviour** — and then writes a test that proves behaviour is unchanged.2728## The Two-Person Workflow2930This skill assumes a hand-off:31321. **Developer** runs the mechanical IDE conversion (`Code > Convert Java File to Kotlin33 File`, or ⌥⇧⌘K), producing a `.kt` file that compiles but is not idiomatic.342. **You (Claude)** drive everything after that:3536 Step 0 Baseline → Step 1 Idiomatic pass → Step 2 Behaviour-locking test → Step 337 Verify. If Step 3 fails or behaviour drifts, loop back to Step 1.3839If you are handed a `.java` file instead, first apply a faithful 1:1 translation to reach40the same starting point, then continue.4142## The Prime Directive: Behaviour Must Not Change4344Every transformation in this skill is **behaviour-preserving**. You are refactoring for45readability, safety, and modern API usage — not adding features or fixing bugs. If you46spot a real bug, surface it to the developer; do not silently "fix" it inside a47conversion. The behaviour-locking test in Step 3 exists to keep you honest.4849## Step 0: Establish Baseline5051Before editing anything:52531. Read the whole `.kt` file (and, if you can, the original `.java` via54 `git show <rev>:<path>.java` or the IDE's local history) to understand *what it does*.552. Write down the **public/observable surface** you must keep intact:56 - Lifecycle callbacks (`onCreate`, `onViewCreated`, `onSaveInstanceState`, …) and their57 ordering of side-effects.58 - Any Parcelable/Bundle keys, intent extras, and `newInstance(...)` factory shapes.593. Note threading: which work runs off the main thread today (`Thread`, `AsyncTask`,60 `runOnUiThread`, executors) — this maps to coroutines in Step 2.6162## Step 1: Idiomatic Pass6364Apply, in this order, then re-check the invariants:65661. **Kill platform types.** Give every `!` platform type an explicit nullable/non-null67 type based on the Java source and call sites.682. **Fail fast.** Replace nested `if`/`else` pyramids and null-checks with guard clauses69 and `require`/`requireNotNull`/`?: return`. See [FAIL-FAST.md](references/FAIL-FAST.md).703. **Decompose.** Break each oversized lifecycle callback / `setupView`-style method into71 small, single-purpose private functions named for their intent. See72 [ANDROID-IDIOMS.md](references/ANDROID-IDIOMS.md).734. **Modern concurrency.** Replace `new Thread`, `AsyncTask`, `runOnUiThread`, and74 callback pairs with `lifecycleScope` + `suspend` + `withContext`. See75 [CONCURRENCY.md](references/CONCURRENCY.md).765. **Modern Android + Kotlin idioms.** Scope functions (`run`/`apply`/`let`), extension77 functions, `when`/`partition`/`filter` over `switch`, string templates, `isNullOrEmpty`,78 view/KTX extensions. See [ANDROID-IDIOMS.md](references/ANDROID-IDIOMS.md). Retire79 deprecated Android APIs (`onActivityResult`, options-menu overrides,80 `java.util.Observable`) — see [DEPRECATED-APIS.md](references/DEPRECATED-APIS.md).816. **Project conventions.** SPDX header, no magic numbers (`companion object` +82 `const val`), resources not hardcoded strings, ≤300 lines/file, ≤120 cols. See83 [PROJECT-CONVENTIONS.md](references/PROJECT-CONVENTIONS.md).847. **Testability seams.** Extract pure logic (URL building, permission math, partitioning)85 into functions you can unit-test; mark with `@VisibleForTesting` where they must stay86 `internal`/`private`-ish but be reachable from tests.8788Do NOT expand scope. Unrelated files stay untouched (AGENTS.md / AI policy).8990## Step 2: Write a Behaviour-Locking Test (Mandatory)9192A conversion is not complete until a test proves behaviour is unchanged. See93[TESTING.md](references/TESTING.md) for the decision tree. In short:9495- **Pure functions you extracted** (e.g. link builders, `isReshareForbidden`,96 partitioning) → fast JVM unit tests in `app/src/test/` (JUnit4 + mockito-kotlin).97- **Fragment/Activity/DB behaviour** → instrumented test in `app/src/androidTest/`98 extending the project's base test class, or a Robolectric test where the project uses it.99- Prefer testing the **seams you just created**. If the Java original had no test, your100 new test is the characterization test that locks current behaviour.101102Every test file gets the SPDX header and follows the project's test conventions.103104## Step 3: Verify105106Run and report real output — never claim green without evidence:107108```bash109# Formatting + static analysis on the changed files110./gradlew spotlessKotlinCheck detektGplayDebug lintGplayDebug spotbugsGplayDebug111112# Unit tests113./gradlew jacocoTestGplayDebugUnitTest114115# Instrumented tests (if you wrote one), scoped to the class116./gradlew createGplayDebugCoverageReport -Pcoverage=true \117 -Pandroid.testInstrumentationRunnerArguments.class=<fully.qualified.TestClass>118```119120## Worked Example121122[assets/worked-example.md](assets/worked-example.md) is a real before/after from123`FileDetailSharingFragment` (871-line Java fragment → idiomatic Kotlin) showing each124transformation class in context. Read it when you need a concrete pattern.125126## Batch Conversion127128Convert one file at a time, leaf dependencies first. Report progress per file. Warn the129developer before a change set grows into several thousand lines — split into focused PRs130(AGENTS.md). Each commit needs `Assisted-by: <agent>:<model>`; only the human adds131`Signed-off-by`.