diktat
Release 2.0.0
Diktat은 Ktlint 위에 구축 된 AST (Abstract Syntax Tree) 방문자로 구현 된 Kotlin 코드 스타일 규칙 모음으로 구성된 Kotlin의 엄격한 코딩 표준입니다. CI/CD (Continuous Integration/Continuous Deployment) 프로세스에서 코드 냄새를 감지하고 자동으로 수정하는 목적을 제공합니다. 지원되는 규칙 및 검사의 포괄적 인 목록을 여기에서 찾을 수 있습니다.
Diktat은 인식을 얻었으며 정적 분석 도구, Kotlin-Awames 및 Kompar 목록에 추가되었습니다. 우리는이 지원을 위해 커뮤니티에 감사를 전합니다!
| 코드 스타일 | 검사 | 예 | 데모 | 백 | 검사 그룹 |
정적 분석을 수행하는 detekt 및 ktlint 와 같은 다른 도구가 있지만 Diktat이 왜 필요한지 궁금 할 것입니다. 주요 이유는 다음과 같습니다.
더 많은 검사 : Diktat은 코드 스타일과 밀접하게 100 개가 넘는 검사를 자랑합니다.
독특한 검사 : Diktat은 다른 Linters에서 찾을 수없는 고유 검사를 소개합니다.
고도로 구성 가능 : 모든 검사는 구성 가능하며 사용자 정의 및 억제가 가능합니다. 구성 옵션 및 억제를 확인하십시오.
엄격한 코드 스타일 : Diktat은 프로젝트에 채택하고 적용 할 수있는 자세한 코드 스타일을 시행합니다.
Diktat를 수동으로 다운로드하십시오 : 여기
또는 curl 사용 :
curl -sSLO https://github.com/saveourtool/diktat/releases/download/v2.0.0/diktat && chmod a+x diktatWindows 전용 . diktat.cmd를 수동으로 다운로드하십시오 : 여기
마지막으로, 'dir/your/dir'에서 '*.kt'파일을 확인하려면 ktlint (diktat가 주입 된)를 실행하십시오.
$ ./diktat " dir/your/dir/**/*.kt "창에서
diktat.bat "dir/your/dir/**/*.kt"
모든 코드 스타일 위반을 자동화 하려면 --mode fix 옵션을 사용하십시오.
예제에서 어떻게 구성되는지 알 수 있습니다.
< plugin >
< groupId >com.saveourtool.diktat</ groupId >
< artifactId >diktat-maven-plugin</ artifactId >
< version >${diktat.version}</ version >
< executions >
< execution >
< id >diktat</ id >
< phase >none</ phase >
< goals >
< goal >check</ goal >
< goal >fix</ goal >
</ goals >
< configuration >
< inputs >
< input >${project.basedir}/src/main/kotlin</ input >
< input >${project.basedir}/src/test/kotlin</ input >
</ inputs >
< diktatConfigFile >diktat-analysis.yml</ diktatConfigFile >
< excludes >
< exclude >${project.basedir}/src/test/kotlin/excluded</ exclude >
</ excludes >
</ configuration >
</ execution >
</ executions >
</ plugin > 만 확인 모드에서만 Diktat를 실행하려면 명령 $ mvn diktat:check@diktat . Autocorrect 모드에서 diktat를 실행하려면 명령 $ mvn diktat:fix@diktat 사용하십시오.
명령 줄에 특정 Maven executionId (위의 예에서 후행 diktat )를 요청하는 것이 필수적 일 수 있습니다.
pom.xml 에는 구성이 다르면 여러 실행이 있습니다 (예 : 여러 규칙 세트) :
< executions >
< execution >
< id >diktat-basic</ id >
< configuration >
< diktatConfigFile >diktat-analysis.yml</ diktatConfigFile >
</ configuration >
</ execution >
< execution >
< id >diktat-advanced</ id >
< configuration >
< diktatConfigFile >diktat-analysis-advanced.yml</ diktatConfigFile >
</ configuration >
</ execution >
</ executions >Diktat 규칙이있는 YAML 파일은 디탈 이외의 이름이 없거나/또는 비 디펜트 위치에 있습니다.
< executions >
< execution >
< id >diktat</ id >
< configuration >
< diktatConfigFile >/non/default/rule-set-file.yml</ diktatConfigFile >
</ configuration >
</ execution >
</ executions >diktatConfigFile 생략하거나 존재하지 않는 파일을 가리키면 diktat가 기본 구성으로 실행될 수 있습니다. executionId 생략하면 :
$ mvn diktat:check -플러그인은 기본 구성을 사용하고 프로젝트 디렉토리에서 diktat-analysis.yml 파일을 검색합니다 (YAML 파일을 편집하여 규칙 세트를 여전히 사용자 정의 할 수 있음).
7.0 이하의 Gradle 버전이 필요합니다
예제에서 플러그인이 어떻게 구성되는지 알 수 있습니다.
plugins {
id( " com.saveourtool.diktat " ) version " 2.0.0 "
}참고 플러그인을 다중 모듈 프로젝트에 적용하려면 "
import com.saveourtool.diktat.plugin.gradle.DiktatGradlePlugin plugins { id( " com.saveourtool.diktat " ) version " 2.0.0 " apply false } allprojects { apply< DiktatGradlePlugin >() }
그런 다음 diktat 확장자를 사용하여 Diktat을 구성 할 수 있습니다.
diktat {
inputs {
include( " src/**/*.kt " ) // path matching this pattern (per PatternFilterable) that will be checked by diktat
exclude( " src/test/kotlin/excluded/** " ) // path matching this pattern will not be checked by diktat
}
debug = true // turn on debug logging
} 또한 diktat Extension에서는 다른 리포터와 출력을 구성 할 수 있습니다. json , html , sarif , plain (기본값)을 지정할 수 있습니다. output 설정되면 파일 경로 여야합니다. 설정하지 않으면 결과가 stdout에 인쇄됩니다. 여러 리포터를 지정할 수 있습니다. 리포터가 지정되지 않으면 plain stdout 과 함께 출력으로 사용됩니다.
diktat {
reporters {
plain()
json()
html {
output = file( " someFile.html " )
}
// checkstyle()
// sarif()
// gitHubActions()
}
} task ./gradlew diktatCheck 사용하여 diktat 검사를 실행하고 task ./gradlew diktatFix 사용하여 오류를 자동으로 수정 할 수 있습니다.
Spotless는 Linter Aggregator입니다.
Diktat은 버전 5.10.0 이후 Spotless-Gradle-Plugin을 통해 실행할 수 있습니다
plugins {
id( " com.diffplug.spotless " ) version " 5.10.0 "
}
spotless {
kotlin {
diktat()
}
kotlinGradle {
diktat()
}
}spotless {
kotlin {
diktat( " 2.0.0 " ).configFile( " full/path/to/diktat-analysis.yml " )
}
}Diktat은 버전 2.8.0 이후 Spotless-Maven-Plugin을 통해 실행할 수 있습니다
< plugin >
< groupId >com.diffplug.spotless</ groupId >
< artifactId >spotless-maven-plugin</ artifactId >
< version >${spotless.version}</ version >
< configuration >
< kotlin >
< diktat />
</ kotlin >
</ configuration >
</ plugin >< diktat >
< version >2.0.0</ version > <!-- optional -->
< configFile >full/path/to/diktat-analysis.yml</ configFile > <!-- optional, configuration file path -->
</ diktat > 우리는 모든 사람들이 CI/CD의 reporter 로 공통 "SARIF"형식을 사용하도록 제안합니다. Github는 Sarif 형식과 통합되어 있으며 풀 요청에서 Diktat 문제에 대한 기본보고를 제공합니다.
Gradle 플러그인 :
githubActions = true
Maven 플러그인 (pom.xml) :
< githubActions >true</ githubActions >Maven 플러그인 (CLI 옵션) :
mvn -B diktat:check@diktat -Ddiktat.githubActions=true
- name : Upload SARIF to Github using the upload-sarif action
uses : github/codeql-action/upload-sarif@v1
if : ${{ always() }}
with :
sarif_file : ${{ github.workspace }} 참고 : codeql-action/upload-sarif 15 세의 업로드 된 파일 수를 제한합니다. 프로젝트에 15 개 이상의 하위 프로젝트가 있으면 한도가 초과되고 단계가 실패합니다. 이 문제를 해결하기 위해 SARIF 보고서를 병합 할 수 있습니다.
diktat-gradle-plugin 기능을 mergeDiktatReports 작업과 함께 제공합니다. 이 작업은 SARIF 보고서를 생성하는 모든 Gradle 프로젝트의 모든 Diktat 작업을보고하고 병합 된 보고서를 루트 프로젝트의 빌드 디렉토리로 출력합니다. 그런 다음이 단일 파일은 GitHub 작업의 입력으로 사용할 수 있습니다.
with :
sarif_file : build/reports/diktat/diktat-merged.sarif diktat-analysis.yml 통한 사용자 정의 Diktat에서는 쉽게 변경할 수있는 diktat-analysis.yml 지원하고 자신의 규칙 세트의 사용자 정의에 도움을주었습니다. 간단한 필드가 있습니다. name - 규칙의 이름, enabled (true/false) - 해당 규칙을 활성화 또는 비활성화하기 위해 (모든 규칙이 기본값에 의해 활성화 됨) configuration -이 특정 규칙에 대한 추가 고유 한 구성의 간단한 맵입니다. 예를 들어:
- name : HEADER_MISSING_OR_WRONG_COPYRIGHT
# all rules are enabled by the default. To disable add 'enabled: false' to the config.
enabled : true
configuration :
isCopyrightMandatory : true
copyrightText : Copyright (c) Jeff Lebowski, 2012-2020. All rights reserved. 프로젝트의 상위 디렉토리에 diktat의 구성이 포함 된 diktat-analysis.yml build.gradle/pom.xml 이 저장하는 것과 동일한 수준으로 지정하고 넣을 수 있습니다.
diktat-analysis.yml의 기본 구성을 참조하십시오
또한 Diktat에서 지원하는 모든 규칙의 목록도 참조하십시오.
예를 들어:
@Suppress( " FUNCTION_NAME_INCORRECT_CASE " )
class SomeClass {
fun methODTREE (): String {
}
}예를 들어:
@Suppress( " diktat " )
class SomeClass {
fun methODTREE (): String {
}
}- name : HEADER_NOT_BEFORE_PACKAGE
enabled : true
ignoreAnnotated : [MyAnnotation, Compose, Controller]이 그룹은 코드 스타일의 장과 연결되어 있습니다.
챕터를 비활성화하려면 다음 구성을 공통 구성에 추가해야합니다 ( - name: DIKTAT_COMMON ).
disabledChapters : " 1, 2, 3 "검사를 챕터로 매핑하는 것은 검사 그룹에서 찾을 수 있습니다.
대규모 기존 프로젝트에서 코드 스타일 분석을 설정할 때 종종 모든 결과를 한 번에 수정할 수있는 능력이 없습니다. 점진적인 채택을 허용하기 위해 Diktat 및 Ktlint는 기준선 모드를 지원합니다. 활성 기준선으로 처음으로 ktlint를 실행하면 기준 파일이 생성됩니다. 도구의 전체 결과 목록이있는 XML 파일입니다. 나중에 호출하면 기준 파일에없는 결과 만보 고됩니다. 기준선은 CLI 플래그로 활성화 될 수 있습니다.
./diktat --baseline=diktat-baseline.xml ** / * .kt또는 Maven 또는 Gradle 플러그인의 해당 구성 옵션. 기준선 보고서는 VCS에 추가 될 예정이지만 필요한 경우 나중에 제거 및 재생할 수 있습니다.
기여 정책 및 행동 강령을 참조하십시오
나는 서문
1. 이름 지정
2. 댓글
3. 일반 서식 (조판)
4. 변수와 유형
5. 기능
6. 클래스, 인터페이스 및 확장 기능
이 문서의 목적은 소프트웨어 개발자가 일관되고 읽기 쉬운 고품질 코드를 작성하는 능력을 향상시키기 위해 소프트웨어 개발자가 참조 할 수있는 사양을 제공하는 것입니다. 이러한 사양은 궁극적으로 소프트웨어 개발 효율성과 제품 경쟁력을 향상시킬 것입니다. 코드가 고품질로 간주 되려면 다음 특성을 수반해야합니다.
다른 현대 프로그래밍 언어와 마찬가지로 Kotlin은 다음과 같은 일반적인 원칙을 준수하는 고급 프로그래밍 언어입니다.
또한 Kotlin에서 프로그래밍 할 때 다음 요소를 고려해야합니다.
깨끗하고 간단한 Kotlin 코드 작성
Kotlin은 기능적 및 객체 지향적 인 두 가지 주요 프로그래밍 패러다임을 결합합니다. 이 두 패러다임은 신뢰할 수 있고 잘 알려진 소프트웨어 엔지니어링 관행입니다. 젊은 프로그래밍 언어로서 Kotlin은 Java, C ++, C#및 Scala와 같은 잘 확립 된 언어 위에 구축되었습니다. 이를 통해 Kotlin은 개발자가 클리너를 작성하고 읽기 쉬운 코드를 작성하는 동시에 복잡한 코드 구조의 수를 줄이는 데 도움이되는 많은 기능을 소개 할 수 있습니다. 예를 들어, 유형 및 null 안전, 확장 기능, Infix 구문, 불변성, Val/var 차별화, 표현 지향 기능, "명령문", 수집, 자동 변환 및 기타 구문 설탕으로 작업하는 경우.
Kotlin 관용구를 따라
Kotlin의 저자 인 Andrey Breslav는 Kotlin이 실용적이고 실용적이지만 학문적이지 않다고 언급했습니다. 실용적인 기능을 통해 아이디어를 실제 작업 소프트웨어로 쉽게 변환 할 수 있습니다. Kotlin은 전임자보다 자연 언어에 더 가깝고, 가독성, 재사용 성, 상호 운용성, 보안 및 도구-프라이언스 (https://blog.jetbrains.com/kotlin/2018/10/kotlinconf-2018-announcements)와 같은 설계 원칙을 구현합니다.
Kotlin을 효율적으로 사용합니다
일부 Kotlin 기능은 리치 코 루틴 라이브러리, 시퀀스, 인라인 함수/클래스, 기본 유형의 배열, 테일 레크 및 계약의 CallinPlace 등 고성능 코드를 작성하는 데 도움이됩니다.
규칙 - 프로그래밍시 따라야하는 규칙.
권장 사항 - 프로그래밍시 고려해야 할 규칙.
설명 - 규칙 및 권장 사항에 대한 필요한 설명.
유효한 예 - 규칙 및 권장 사항의 권장 예.
유효하지 않은 예 - 규칙 및 권장 사항의 권장되지 않은 예.
달리 명시되지 않는 한,이 사양은 Kotlin의 버전 1.3 이상에 적용됩니다.
예외가 존재할 수 있지만 규칙과 권장 사항이 필요한 이유를 이해하는 것이 필수적입니다. 프로젝트 상황이나 개인 습관에 따라 규칙 중 일부를 위반할 수 있습니다. 그러나 한 가지 예외는 많은 것으로 이어질 수 있으며 결국 코드 일관성을 파괴 할 수 있습니다. 따라서 예외는 거의 없어야합니다. 오픈 소스 코드 또는 타사 코드를 수정할 때 기존 사양을 사용하는 대신이 오픈 소스 프로젝트의 코드 스타일을 사용하여 일관성을 유지할 수 있습니다. Android Framework와 같은 Android 기본 운영 체제 인터페이스를 직접 기반으로하는 소프트웨어는 Android 스타일과 일치합니다.
프로그래밍에서 변수, 기능, 클래스 등을 의미 있고 적절하게 이름을 지정하는 것이 항상 쉬운 것은 아닙니다.
참고 : 소스 파일 인코딩 형식 (주석 포함)은 UTF-8이어야합니다. ASCII 수평 공간 문자 (0x20, 즉 공간)는 유일하게 허용되는 공백 문자입니다. 탭은 들여 쓰기에 사용해서는 안됩니다.
이 섹션에서는 이름 지정 식별자에 대한 일반적인 규칙에 대해 설명합니다.
식별자의 경우 다음 이름 지정 규칙을 사용하십시오.
모든 식별자는 ASCII 문자 또는 숫자 만 사용해야하며 이름은 정규 표현식 w{2,64} 와 일치해야합니다. 설명 : 각 유효한 식별자 이름은 정규 표현식 w{2,64} 와 일치해야합니다. {2,64} 이름 길이가 2 ~ 64 자임을 의미하며 변수 이름의 길이는 수명 범위, 기능 및 책임에 비례해야합니다. 31 자 미만의 이름 길이는 일반적으로 권장됩니다. 그러나 이것은 프로젝트에 따라 다릅니다. 그렇지 않으면, 슈퍼 클래스에서 제네릭 또는 상속이있는 클래스 선언은 선이 파손될 수 있습니다. 이름으로 특수 접두사 또는 접미사를 사용해서는 안됩니다. 다음 예제는 Name_, Mname, S_name 및 Kname의 부적절한 이름입니다.
내용을 설명하는 파일 이름을 선택하십시오. 낙타 케이스 (Pascalcase) 및 .kt 확장을 사용하십시오.
이름 지정의 전형적인 예 :
| 의미 | 옳은 | 잘못된 |
|---|---|---|
| "XML HTTP 요청" | xmlhttprequest | xmlhttprequest |
| "새로운 고객 ID" | NewCustomerid | NewCustomerid |
| "내부 스톱워치" | Innerstopwatch | Innerstopwatch |
| "iOS에서 IPv6을 지원합니다" | SupportSIPV6ONIOS | SupportSIPV6ONIOS |
| "YouTube 수입업자" | YouTubeImporter | YouTubeImporter |
val `my dummy name - with - minus` = " value " 유일한 예외는 Unit tests.
@Test fun `my test` () { /* ... */ }| 예상되는 | 혼란스러운 이름 | 제안 된 이름 |
|---|---|---|
| 0 (0) | o, d | obj, dgt |
| 1 (1) | 나, l | 그것은 ln, 라인 |
| 2 (2) | 지 | N1, N2 |
| 5 (5) | 에스 | xs, str |
| 6 (6) | 이자형 | Ex, Elm |
| 8 (8) | 비 | BT, NXT |
| n, h | H, n | NR, 머리, 높이 |
| Rn, m | M, RN | MBR, 항목 |
예외 :
e 변수는 Catch Block : catch (e: Exception) {} 의 예외를 예외로 사용하는 데 사용될 수 있습니다.| 유형 | 이름 지정 스타일 |
|---|---|
| 인터페이스, 클래스, 주석, 열거 형 유형 및 객체 유형 이름 | 대문자로 시작하는 낙타 사건. 테스트 클래스에는 테스트 접미사가 있습니다. 파일 이름은 'topclassname'.kt입니다. |
| 클래스 필드, 로컬 변수, 메소드 및 메소드 매개 변수 | 낮은 사례 편지로 시작하는 낙타 케이스. 테스트 방법은 '_'로 밑줄을 긋을 수 있습니다. 유일한 예외는 후원 속성입니다. |
| 정적 상수 및 열거 된 값 | '_'로 밑줄이 그어진 대문자 만 |
| 일반 유형 변수 | 숫자가 뒤 따르는 단일 대문자 (예 : E, T, U, X, T2 |
| 예외 | 클래스 이름과 동일하지만 접미사 예외는 예를 들어 다음과 같습니다. AccessException 및 NullPointerException |
패키지 이름은 소문자이며 점으로 분리됩니다. 회사 내에서 개발 된 코드는 your.company.domain. 숫자는 패키지 이름으로 허용됩니다. 각 파일에는 package 지침이 있어야합니다. 패키지 이름은 모두 소문자로 작성되며 연속 단어가 함께 연결됩니다 (밑줄 없음). 패키지 이름에는 다른 팀과의 충돌을 방지하기 위해 제품 또는 모듈 이름과 부서 (또는 팀) 이름이 모두 포함되어야합니다. 숫자는 허용되지 않습니다. 예 : org.apache.commons.lang3 , xxx.yyy.v2
예외 :
your.company.domain.com.example._123name .org.example.hyphenated_name , int_.example 과 같은 예약 된 Java/Kotlin 키워드가 포함 된 경우 밑줄이 허용됩니다.Valid example :
package your.company.domain.mobilecontrol.views이 섹션에서는 명명 클래스, 열거 및 인터페이스에 대한 일반적인 규칙에 대해 설명합니다.
클래스, 열거 및 인터페이스 이름은 UpperCamelCase 명명법을 사용합니다. 아래에 설명 된 이름 지정 규칙을 따르십시오.
클래스 이름은 일반적으로 어퍼 카멜 케이스와 같은 낙타 케이스 명명법을 사용하여 명사 (또는 명사구)입니다. 예를 들면 : Character 또는 ImmutableList . 인터페이스 이름은 또한 명사 또는 명사구 (예 : List ) 또는 형용사 또는 형용사 문구 (예 : Readable ) 일 수도 있습니다. 동사는 클래스의 이름을 지정하는 데 사용되지 않습니다. 그러나 명사 (예 : Customer , WikiPage 및 Account )를 사용할 수 있습니다. Manager 및 Process 와 같은 모호한 단어를 사용하지 마십시오.
테스트 클래스는 테스트중인 클래스의 이름으로 시작하고 '테스트'로 끝납니다. 예를 들어, HashTest 또는 HashIntegrationTest .
유효하지 않은 예 :
class marcoPolo {}
class XMLService {}
interface TAPromotion {}
class info {}Valid example :
class MarcoPolo {}
class XmlService {}
interface TaPromotion {}
class Order {}이 섹션에서는 이름 지정 기능에 대한 일반적인 규칙에 대해 설명합니다.
함수 이름은 lowerCamelCase 명명법을 사용해야합니다. 아래에 설명 된 이름 지정 규칙을 따르십시오.
lowerCamelCase )으로 표시되는 동사 또는 동사 문구입니다. 예를 들어 : sendMessage , stopProcess 또는 calculateValue . 함수의 이름을 지정하려면 다음 서식 규칙을 사용하십시오.a) 특정 값을 얻거나 수정 또는 계산하려면 : get + non-boolean field (). Kotlin 컴파일러는 일부 클래스에 대한 getters를 자동으로 생성하여 'get'필드에 선호되는 특수 구문을 적용합니다. Kotlin Private Val Field : String get () {}. Kotlin Private Val 필드 : String get () {}.
private val field : String
get() {
}참고 : 호출 속성 액세스 구문은 Getter를 직접 호출하는 것이 선호됩니다. 이 경우 Kotlin 컴파일러는 자동으로 해당 Getter를 호출합니다.
b) is + 부울 변수 이름 ()
c) set + field/attribute name (). 그러나 Kotlin의 구문 및 코드 생성은 지점 a의 getters에 대해 설명한 것과 완전히 동일합니다.
d) has + noun / adjective ()
e) 동사 () 참고 : 참고 : 동사는 주로 document.print () 와 같은 동작 객체에 사용됩니다.
f) 동사 + 명사 ()
g) 콜백 함수는 onCreate() 과 같은 전치사 + 동사 형식 onDestroy() 사용하는 이름을 허용 toString() .
유효하지 않은 예 :
fun type (): String
fun Finished (): Boolean
fun visible (boolean)
fun DRAW ()
fun KeyListener ( Listener )Valid example :
fun getType (): String
fun isFinished (): Boolean
fun setVisible (boolean)
fun draw ()
fun addKeyListener ( Listener )_ )은 Junit 테스트 기능 이름에 포함될 수 있으며 분리기로 사용해야합니다. 각 논리적 부분은 밑줄을 사용하는 일반적인 패턴과 같은 lowerCamelCase 로 표시됩니다 : pop_emptyStack .이 섹션에서는 명명 제약 조건에 대한 일반적인 규칙을 설명합니다.
상수 이름은 밑줄로 분리 된 단어로 상반되어야합니다. 일반 상수 이름 지정 규칙은 다음과 같습니다.
const 키워드 또는 최상위/ val 로컬 변수로 생성 된 속성입니다. 대부분의 경우 상수는 object / companion object / 파일 상단 레벨에서 const val 속성으로 식별 될 수 있습니다. 이 변수에는 프로그래머가 일반적으로 변경해서는 안되는 고정 상수 값이 포함되어 있습니다. 여기에는 기본 유형, 문자열, 불변 유형 및 불변의 불변 유형의 불변 컬렉션이 포함됩니다. 상태를 변경할 수있는 객체의 값은 일정하지 않습니다.val 변수가 상수는 아닙니다.Logger 및 Lock 과 같은 불변의 내용이있는 물체는 상수로 말하거나 낙타 케이스를 일반 변수로 가질 수 있습니다.magic numbers 대신 의미있는 상수를 사용하십시오. SQL 또는 로깅 스트링은 마법 번호로 취급되어서는 안되며 문자열 상수로 정의되어서는 안됩니다. NUM_FIVE = 5 또는 NUM_5 = 5 와 같은 마법 상수는 상수로 취급해서는 안됩니다. 이는 NUM_5 = 50 또는 55로 변경하면 실수가 쉽게 이루어질 수 있기 때문입니다. 이러한 상수는 일반적으로 알고리즘의 측정, 용량, 범위, 위치, 세율, 홍보 할인 및 전력 기반 배수와 같은 비즈니스 논리 값을 나타냅니다. 다음 방법으로 마법 숫자를 사용하지 않을 수 있습니다.size == 0 확인하는 대신 isEmpty() 함수를 사용하십시오. time 과 함께 작업하려면 java.time API 의 내장을 사용하십시오.유효하지 않은 예 :
var int MAXUSERNUM = 200 ;
val String sL = " Launcher " ;Valid example :
const val int MAX_USER_NUM = 200 ;
const val String APPLICATION_NAME = " Launcher " ;이 섹션에서는 이름 지정 변수에 대한 일반적인 규칙을 설명합니다.
비 정통 필드 이름은 낙타 케이스를 사용하고 소문자로 시작해야합니다. 로컬 변수는 최종적이고 불변이더라도 일정하게 취급 될 수 없습니다. 따라서 이전 규칙을 사용해서는 안됩니다. 수집 유형 변수 (세트, 목록 등)의 이름에는 복수 명사가 포함되어야합니다. 예를 들면 : var namesList: List<String>
비정규 변수의 이름은 lowerCamelCase 사용해야합니다. 싱글 톤 객체를 저장하는 데 사용되는 최종 불변 필드의 이름은 동일한 낙타 케이스 표기법을 사용할 수 있습니다.
유효하지 않은 예 :
customername : String
user : List < String > = listof()Valid example :
var customerName : String
val users : List < String > = listOf ();
val mutableCollection : MutableSet < String > = HashSet ()부정적인 의미를 가진 부울 변수 이름을 사용하지 마십시오. 논리적 연산자와 부정적인 의미를 가진 이름을 사용하는 경우 코드를 이해하기 어려울 수 있으며, 이는 "이중 네거티브"라고합니다. 예를 들어,! is noterror의 의미를 이해하기 쉽지 않습니다. Javabeans 사양은 부울 클래스의 속성에 대한 isxxx () getters를 자동으로 생성합니다. 그러나 부울 유형을 반환하는 모든 방법 이이 표기법을 가지고있는 것은 아닙니다. 부울 로컬 변수 또는 방법의 경우 IS (일반적으로 Javabeans에서 일반적으로 사용), Has, Has, Can, Lust 및 Should를 포함하여 의미가없는 접두사를 추가하는 것이 좋습니다. Intellij와 같은 최신 통합 개발 환경 (IDES)은 이미 Java에서 Getters를 생성 할 때이 작업을 수행 할 수 있습니다. Kotlin의 경우,이 프로세스는 모든 것이 후드 아래의 바이트 코드 레벨에 있기 때문에 훨씬 더 간단합니다.
유효하지 않은 예 :
val isNoError : Boolean
val isNotFound : Boolean
fun empty ()
fun next ();Valid example :
val isError : Boolean
val isFound : Boolean
val hasLicense : Boolean
val canEvaluate : Boolean
val shouldAbort : Boolean
fun isEmpty ()
fun hasNext ()모범 사례는 한 문장이 될 수있는 요약으로 코드를 시작하는 것입니다. 각 코드 라인에 대한 의견을 전혀 쓰지 않고 명백한 논평 진술 사이의 균형을 유지하십시오. 수업, 인터페이스 또는 메소드의 이름을 반복하지 않고 의견을 정확하고 명확하게 표현해야합니다. 의견은 잘못된 코드에 대한 해결책이 아닙니다. 대신, 문제가 발생하거나 문제를 해결하려는 즉시 코드를 수정해야합니다 (Jira 번호를 포함한 Todo Comment를 입력하여). 의견은 코드의 디자인 아이디어와 논리를 정확하게 반영하고 비즈니스 논리를 더 설명해야합니다. 결과적으로 다른 프로그래머는 코드를 이해하려고 할 때 시간을 절약 할 수 있습니다. 앞으로 코드의 원래 아이디어를 이해하는 데 도움이되는 의견을 작성하고 있다고 상상해보십시오.
KDOC는 Javadoc의 블록 태그 구문 (Kotlin의 특정 구성을 지원하기 위해 확장)과 Markdown의 인라인 마크 업의 조합입니다. KDOC의 기본 형식은 다음 예에 표시됩니다.
/* *
* There are multiple lines of KDoc text,
* Other ...
*/
fun method ( arg : String ) {
// ...
}또한 다음 단일 라인 형식으로 표시됩니다.
/* * Short form of KDoc. */전체 KDOC 블록을 한 줄에 저장할 때 단일 라인 양식을 사용하십시오 (KDOC 마크 @XXX는 없습니다). KDOC 사용 방법에 대한 자세한 지침은 공식 문서를 참조하십시오.
최소한 KDOC는 모든 대중, 보호 또는 내부 장식 클래스, 인터페이스, 열거, 방법 및 멤버 필드 (속성)에 사용해야합니다. 다른 코드 블록에는 필요한 경우 KDOC가있을 수 있습니다. 클래스의 기본 생성자에서 속성 전에 주석 또는 KDOC를 사용하는 대신 클래스의 KDOC에서 @property 태그를 사용하십시오. 1 차 생성자의 모든 속성은 @property 태그가있는 KDOC에도 문서화되어야합니다.
잘못된 예 :
/* *
* Class description
*/
class Example (
/* *
* property description
*/
val foo : Foo ,
// another property description
val bar : Bar
)Correct example:
/* *
* Class description
* @property foo property description
* @property bar another property description
*/
class Example (
val foo : Foo ,
val bar : Bar
)잘못된 예 :
class Example {
fun doGood () {
/* *
* wrong place for kdoc
*/
1 + 2
}
}Correct Example:
class Example {
fun doGood () {
/*
* right place for block comment
*/
1 + 2
}
}예외 :
Setters/Getters of Properties의 경우 명백한 의견 ( this getter returns field 와 같은)은 선택 사항입니다. Kotlin은 후드 아래에서 간단한 get/set 메소드를 생성합니다.
아래 예제에 표시된 것과 같이 간단한 단일 라인 메소드에 대한 주석을 추가하는 것이 선택 사항입니다.
val isEmpty : Boolean
get() = this .size == 0또는
fun isEmptyList ( list : List < String >) = list.size == 0참고 : 슈퍼 클래스 메소드와 거의 동일하다면 메소드의 재정의를 위해 KDOC를 건너 뛸 수 있습니다.
이 메소드에 인수, 반환 값 또는 예외를 던질 수있는 세부 사항이있는 경우 kdoc 블록 (@param, @return, @throws 등)에 설명해야합니다.
유효한 예 :
/* *
* This is the short overview comment for the example interface.
* / * Add a blank line between the comment text and each KDoc tag underneath * /
* @since 1.6
*/
protected abstract class Sample {
/* *
* This is a long comment with whitespace that should be split in
* comments on multiple lines if the line comment formatting is enabled.
* / * Add a blank line between the comment text and each KDoc tag underneath * /
* @param fox A quick brown fox jumps over the lazy dog
* @return battle between fox and dog
*/
protected abstract fun foo ( Fox fox)
/* *
* These possibilities include: Formatting of header comments
* / * Add a blank line between the comment text and each KDoc tag underneath * /
* @return battle between fox and dog
* @throws ProblemException if lazy dog wins
*/
protected fun bar () throws ProblemException {
// Some comments / * No need to add a blank line here * /
var aVar = .. .
// Some comments / * Add a blank line before the comment * /
fun doSome ()
}
}KDOC 태그와 내용 사이에는 공간이 하나만 있어야합니다. 태그는 다음 순서로 정렬됩니다 : @param, @return 및 @throws.
따라서 KDOC는 다음을 포함해야합니다.
implSpec , apiNote 및 implNote )에는 빈 줄이 필요합니다.@implSpec : API 구현과 관련된 사양이므로 구현자가이를 재정의할지 여부를 결정할 수 있습니다.@apiNote : NULL 허용 여부와 메소드가 스레드-안전인지, 알고리즘 복잡성, 입력 및 출력 범위, 예외 등을 포함한 API 예방 조치를 설명하십시오.@implNote : 구현자가 명심 해야하는 API 구현과 관련된 메모.@param , @return , @throws 및 기타 의견이 이어집니다.@param , @return , @throws . KDOC는 다음을 포함해서는 안됩니다.*/ symbols).@author 태그. 변화 기록을 살펴보기 위해 선택한 git blame 또는 VC를 사용할 수있을 때 누가 원래 수업을 만들었는지는 중요하지 않습니다. 중요한 메모 :@deprecated 태그를 지원하지 않습니다. 대신 @Deprecated 주석을 사용하십시오.@since 태그는 버전에만 사용해야합니다. @since 태그에서 날짜를 사용하지 않으면 혼란스럽고 정확하지 않습니다. 태그 블록을 한 줄로 설명 할 수없는 경우 @ 위치에서 4 개의 공간 으로 새 라인의 내용을 들여내어 정렬을 달성합니다 ( @ 카운트 1 + 3 개의 공간).
예외:
When the descriptive text in a tag block is too long to wrap, you can indent the alignment with the descriptive text in the last line. The descriptive text of multiple tags does not need to be aligned. See 3.8 Horizontal space.
In Kotlin, compared to Java, you can put several classes inside one file, so each class should have a Kdoc formatted comment (as stated in rule 2.1). This comment should contain @since tag. The right style is to write the application version when its functionality is released. It should be entered after the @since tag.
예 :
/* *
* Description of functionality
*
* @since 1.6
*/Other KDoc tags (such as @param type parameters and @see.) can be added as follows:
/* *
* Description of functionality
*
* @apiNote: Important information about API
*
* @since 1.6
*/This section describes the general rules of adding comments on the file header.
Comments on the file header should be placed before the package name and imports. If you need to add more content to the comment, subsequently add it in the same format.
Comments on the file header must include copyright information, without the creation date and author's name (use VCS for history management). Also, describe the content inside files that contain multiple or no classes.
The following examples for Huawei describe the format of the copyright license :
Chinese version:版权所有 (c) 华为技术有限公司 2012-2020
English version: Copyright (c) Huawei Technologies Co., Ltd. 2012-2020. All rights reserved. 2012 and 2020 are the years the file was first created and the current year, respectively.
Do not place release notes in header, use VCS to keep track of changes in file. Notable changes can be marked in individual KDocs using @since tag with version.
Invalid example:
/* *
* Release notes:
* 2019-10-11: added class Foo
*/
class FooValid example:
/* *
* @since 2.4.0
*/
class Foo The copyright statement can use your company's subsidiaries, as shown in the below examples:
Chinese version:版权所有 (c) 海思半导体 2012-2020
English version: Copyright (c) Hisilicon Technologies Co., Ltd. 2012-2020. All rights reserved.
The copyright information should not be written in KDoc style or use single-line comments. It must start from the beginning of the file. The following example is a copyright statement for Huawei, without other functional comments:
/*
* Copyright (c) Huawei Technologies Co., Ltd. 2012-2020. All rights reserved.
*/The following factors should be considered when writing the file header or comments for top-level classes:
*/ symbol. If it is a comment for a top-level class, the class declaration should start immediately without using a newline.@apiNote , the entire tag block should be deleted.Comments on the function header are placed above function declarations or definitions. A newline should not exist between a function declaration and its Kdoc. Use the preceding <<c2.1,KDoc>> style rules.
As stated in Chapter 1, the function name should reflect its functionality as much as possible. Therefore, in the Kdoc, try to describe the functionality that is not mentioned in the function name. Avoid unnecessary comments on dummy coding.
The function header comment's content is optional, but not limited to function description, return value, performance constraints, usage, memory conventions, algorithm implementation, reentrant requirements, etc.
This section describes the general rules of adding code comments.
It is a good practice to add a blank line between the body of the comment and Kdoc tag-blocks. Also, consider the following rules:
Valid Examples:
/* *
* This is the short overview comment for the example interface.
*
* @since 1.6
*/
public interface Example {
// Some comments /* Since it is the first member definition in this code block, there is no need to add a blank line here */
val aField : String = .. .
/* Add a blank line above the comment */
// Some comments
val bField : String = .. .
/* Add a blank line above the comment */
/* *
* This is a long comment with whitespace that should be split in
* multiple line comments in case the line comment formatting is enabled.
* /* blank line between description and Kdoc tag */
* @param fox A quick brown fox jumps over the lazy dog
* @return the rounds of battle of fox and dog
*/
fun foo ( Fox fox)
/* Add a blank line above the comment */
/* *
* These possibilities include: Formatting of header comments
*
* @return the rounds of battle of fox and dog
* @throws ProblemException if lazy dog wins
*/
fun bar () throws ProblemException {
// Some comments /* Since it is the first member definition in this range, there is no need to add a blank line here */
var aVar = .. .
// Some comments /* Add a blank line above the comment */
fun doSome ()
}
}if-else-if scenario, put the comments inside the else-if branch or in the conditional block, but not before the else-if . This makes the code more understandable. When the if-block is used with curly braces, the comment should be placed on the next line after opening the curly braces. Compared to Java, the if statement in Kotlin statements returns a value. For this reason, a comment block can describe a whole if-statement .Valid examples:
val foo = 100 // right-side comment
val bar = 200 /* right-side comment */
// general comment for the value and whole if-else condition
val someVal = if (nr % 15 == 0 ) {
// when nr is a multiple of both 3 and 5
println ( " fizzbuzz " )
} else if (nr % 3 == 0 ) {
// when nr is a multiple of 3, but not 5
// We print "fizz", only.
println ( " fizz " )
} else if (nr % 5 == 0 ) {
// when nr is a multiple of 5, but not 3
// we print "buzz" only.
println ( " buzz " )
} else {
// otherwise, we print the number.
println (x)
}// , /* , /** and * )Valid example:
val x = 0 // this is a comment Do not comment on unused code blocks, including imports. Delete these code blocks immediately. A code is not used to store history. Git, svn, or other VCS tools should be used for this purpose. Unused imports increase the coupling of the code and are not conducive to maintenance. The commented out code cannot be appropriately maintained. In an attempt to reuse the code, there is a high probability that you will introduce defects that are easily missed. The correct approach is to delete the unnecessary code directly and immediately when it is not used anymore. If you need the code again, consider porting or rewriting it as changes could have occurred since you first commented on the code.
The code officially delivered to the client typically should not contain TODO/FIXME comments. TODO comments are typically used to describe modification points that need to be improved and added. For example, refactoring FIXME comments are typically used to describe known defects and bugs that will be subsequently fixed and are not critical for an application. They should all have a unified style to facilitate unified text search processing.
예:
// TODO(<author-name>): Jira-XXX - support new json format
// FIXME: Jira-XXX - fix NPE in this code blockAt a version development stage, these annotations can be used to highlight the issues in the code, but all of them should be fixed before a new product version is released.
This section describes the rules related to using files in your code.
If the file is too long and complicated, it should be split into smaller files, functions, or modules. Files should not exceed 2000 lines (non-empty and non-commented lines). It is recommended to horizontally or vertically split the file according to responsibilities or hierarchy of its parts. The only exception to this rule is code generation - the auto-generated files that are not manually modified can be longer.
A source file contains code blocks in the following order: copyright, package name, imports, and top-level classes. They should be separated by one blank line.
a) Code blocks should be in the following order:
@file annotationb) Each of the preceding code blocks should be separated by a blank line.
c) Import statements are alphabetically arranged, without using line breaks and wildcards ( wildcard imports - * ).
d) Recommendation : One .kt source file should contain only one class declaration, and its name should match the filename
e) Avoid empty files that do not contain the code or contain only imports/comments/package name
f) Unused imports should be removed
From top to bottom, the order is the following:
Each category should be alphabetically arranged. Each group should be separated by a blank line. This style is compatible with Android import order.
Valid example :
import android.* // android
import androidx.* // android
import com.android.* // android
import com.your.company.* // your company's libs
import your.company.* // your company's libs
import com.fasterxml.jackson.databind.ObjectMapper // other third-party dependencies
import org.junit.jupiter.api.Assertions
import java.io.IOException // java core packages
import java.net.URL
import kotlin.system.exitProcess // kotlin standard library
import kotlinx.coroutines.* // official kotlin extension library The declaration parts of class-like code structures (class, interface, etc.) should be in the following order: compile-time constants (for objects), class properties, late-init class properties, init-blocks, constructors, public methods, internal methods, protected methods, private methods, and companion object. Blank lines should separate their declaration. 참고 :
const val ) in companion objects should be alphabetically arranged.The declaration part of a class or interface should be in the following order:
Exception: All variants of a private val logger should be placed at the beginning of the class ( private val log , LOG , logger , etc.).
Kotlin allows several top-level declaration types: classes, objects, interfaces, properties and functions. When declaring more than one class or zero classes (eg only functions), as per rule 2.2.1, you should document the whole file in the header KDoc. When declaring top-level structures, keep the following order:
const val , val , lateinit var , var )Note : Extension functions shouldn't have receivers declared in the same file according to rule 6.2.3
Valid example:
package com.saveourtool.diktat.example
const val CONSTANT = 42
val topLevelProperty = " String constant "
internal typealias ExamplesHandler = ( IExample ) -> Unit
interface IExample
class Example : IExample
private class Internal
fun Other. asExample (): Example { /* ... */ }
private fun Other. asInternal (): Internal { /* ... */ }
fun doStuff () { /* ... */ } Note : kotlin scripts (.kts) allow arbitrary code to be placed on the top level. When writing kotlin scripts, you should first declare all properties, classes and functions. Only then you should execute functions on top level. It is still recommended wrapping logic inside functions and avoid using top-level statements for function calls or wrapping blocks of code in top-level scope functions like run .
예:
/* class declarations */
/* function declarations */
run {
// call functions here
}This section describes the general rules of using braces in your code.
Braces should always be used in if , else , for , do , and while statements, even if the program body is empty or contains only one statement. In special Kotlin when statements, you do not need to use braces for single-line statements.
Valid example:
when (node.elementType) {
FILE -> {
checkTopLevelDoc(node)
checkSomething()
}
CLASS -> checkClassElements(node)
} Exception: The only exception is ternary operator in Kotlin (a single line if () <> else <> )
Invalid example:
val value = if (string.isEmpty()) // WRONG!
0
else
1Valid example :
val value = if (string.isEmpty()) 0 else 1 // Okay if (condition) {
println ( " test " )
} else {
println ( 0 )
}For non-empty blocks and block structures, the opening brace is placed at the end of the line. Follow the K&R style (1TBS or OTBS) for non-empty code blocks with braces:
else , finally , and while (from do-while statement), or catch keywords. These keywords should not be split from the closing brace by a newline character.Exception cases :
-> ) (see point 5 of Rule 3.6.2). arg.map { value ->
foo(value)
}else / catch / finally / while (from do-while statement) keywords closing brace should stay on the same line: do {
if ( true ) {
x ++
} else {
x --
}
} while (x > 0 )Valid example:
return arg.map { value ->
while (condition()) {
method()
}
value
}
return MyClass () {
@Override
fun method () {
if (condition()) {
try {
something()
} catch (e : ProblemException ) {
recover()
}
} else if (otherCondition()) {
somethingElse()
} else {
lastThing()
}
}
} Only spaces are permitted for indentation, and each indentation should equal four spaces (tabs are not permitted). If you prefer using tabs, simply configure them to change to spaces in your IDE automatically. These code blocks should be indented if they are placed on the new line, and the following conditions are met:
+ / - / && / = /etc.)someObject
.map()
.filter()arg.map { value ->
foo(value)
}Exceptions :
Argument lists:
a) Eight spaces are used to indent argument lists (both in declarations and at call sites).
b) Arguments in argument lists can be aligned if they are on different lines.
Eight spaces are used if there is a newline after any binary operator.
Eight spaces are used for functional-like styles when the newline is placed before the dot.
Supertype lists:
a) Four spaces are used if the colon before the supertype list is on a new line.
b) Four spaces are used before each supertype, and eight spaces are used if the colon is on a new line.
Note: there should be an indentation after all statements such as if , for , etc. However, according to this code style, such statements require braces.
if (condition)
foo()Exceptions :
8 spaces . A parameter that was moved to a new line can be on the same level as the previous argument: fun visit (
node : ASTNode ,
autoCorrect : Boolean ,
params : KtLint . ExperimentalParams ,
emit : (offset: Int , errorMessage: String , canBeAutoCorrected: Boolean ) -> Unit
) {
}+ / - / * can be indented with 8 spaces : val abcdef = " my splitted " +
" string "lintMethod(
"""
|val q = 1
|
""" .trimMargin()
)4 spaces if they are on different lines or with 8 spaces if the leading colon is also on a separate line class A :
B ()
class A
:
B () Avoid empty blocks, and ensure braces start on a new line. An empty code block can be closed immediately on the same line and the next line. However, a newline is recommended between opening and closing braces {} (see the examples below.)
Generally, empty code blocks are prohibited; using them is considered a bad practice (especially for catch block). They are appropriate for overridden functions, when the base class's functionality is not needed in the class-inheritor, for lambdas used as a function and for empty function in implementation of functional interface.
override fun foo () {
}Valid examples (note once again that generally empty blocks are prohibited):
fun doNothing () {}
fun doNothingElse () {
}
fun foo ( bar : () -> Unit = {})Invalid examples:
try {
doSomething()
} catch (e : Some ) {}Use the following valid code instead:
try {
doSomething()
} catch (e : Some ) {
}Line length should be less than 120 symbols. Otherwise, it should be split.
If complex property initializing is too long, It should be split into priorities:
Invalid example:
val complexProperty = 1 + 2 + 3 + 4Valid example:
val complexProperty = 1 + 2 +
3 + 4Invalid example:
val complexProperty = ( 1 + 2 + 3 > 0 ) && ( 23 * 4 > 10 * 6 )Valid example:
val complexProperty = ( 1 + 2 + 3 > 0 ) &&
( 23 * 4 > 10 * 6 ) If long line should be split in Elvis Operator (?:), it`s done like this
Invalid example:
val value = first ? : secondValid example:
val value = first
? : second If long line in Dot Qualified Expression or Safe Access Expression , it`s done like this:
Invalid example:
val value = This . Is . Very . Long . Dot . Qualified . ExpressionValid example:
val value = This . Is . Very . Long
. Dot . Qualified . ExpressionInvalid example:
val value = This . Is ?. Very ?. Long? . Safe ?. Access ?. ExpressionValid example:
val value = This . Is ?. Very ?. Long
?. Safe ?. Access ?. Expression if value arguments list is too long, it also should be split:
Invalid example:
val result1 = ManyParamInFunction (firstArgument, secondArgument, thirdArgument, fourthArgument, fifthArguments)Valid example:
val result1 = ManyParamInFunction (firstArgument,
secondArgument, thirdArgument, fourthArgument,
fifthArguments) If annotation is too long, it also should be split:
Invalid example:
@Query(value = " select * from table where age = 10 " , nativeQuery = true )
fun foo () {}Valid example:
@Query(
value = " select * from table where age = 10 " ,
nativeQuery = true )
fun foo () {} Long one line function should be split:
Invalid example:
fun foo () = goo().write( " TooLong " )Valid example:
fun foo () =
goo().write( " TooLong " ) Long binary expression should be split into priorities:
Invalid example:
if (( x > 100 ) || y < 100 && ! isFoo()) {}Valid example:
if (( x > 100 ) ||
y < 100 && ! isFoo()) {} String template also can be split in white space in string text
Invalid example:
val nameString = " This is very long string template "Valid example:
val nameString = " This is very long " +
" string template " Long Lambda argument should be split:
Invalid example:
val variable = a?.filter { it.elementType == true } ? : nullValid example:
val variable = a?.filter {
it.elementType == true
} ? : null Long one line When Entry should be split:
Invalid example:
when (elem) {
true -> long.argument.whenEntry
}Valid example:
when (elem) {
true -> {
long.argument.whenEntry
}
} If the examples above do not fit, but the line needs to be split and this in property , this is fixed like thisЖ
Invalid example:
val element = veryLongNameFunction(firstParam)Valid example:
val element =
varyLongNameFunction(firstParam) Eol comment also can be split, but it depends on comment location. If this comment is on the same line with code it should be on line before:
Invalid example:
fun foo () {
val name = " Nick " // this comment is too long
}Valid example:
fun foo () {
// this comment is too long
val name = " Nick "
}But if this comment is on new line - it should be split to several lines:
Invalid example:
// This comment is too long. It should be on two lines.
fun foo () {}Valid example:
// This comment is too long.
// It should be on two lines.
fun foo () {} The international code style prohibits non-Latin ( non-ASCII ) symbols. (See Identifiers) However, if you still intend on using them, follow the following convention:
One wide character occupies the width of two narrow characters. The "wide" and "narrow" parts of a character are defined by its east Asian width Unicode attribute. Typically, narrow characters are also called "half-width" characters. All characters in the ASCII character set include letters (such as a, A ), numbers (such as 0, 3 ), and punctuation spaces (such as , , { ), all of which are narrow characters. Wide characters are also called "full-width" characters. Chinese characters (such as中, 文), Chinese punctuation ( ， , ； ), full-width letters and numbers (such as Ａ、３ ) are "full-width" characters. Each one of these characters represents two narrow characters.
Any line that exceeds this limit ( 120 narrow symbols ) should be wrapped, as described in the Newline section.
Exceptions:
package and import statements.This section contains the rules and recommendations on using line breaks.
Each line can have a maximum of one code statement. This recommendation prohibits the use of code with ; because it decreases code visibility.
Invalid example:
val a = " " ; val b = " "Valid example:
val a = " "
val b = " " ; ) after each statement separated by a newline character. There should be no redundant semicolon at the end of the lines. When a newline character is needed to split the line, it should be placed after such operators as && / || / + /etc. and all infix functions (for example, xor ). However, the newline character should be placed before operators such as . , ?. , ?: , 그리고 :: .
Note that all comparison operators, such as == , > , < , should not be split.
Invalid example :
if (node !=
null && test != null ) {}Valid example :
if (node != null &&
test != null ) {
} Note: You need to follow the functional style, meaning each function call in a chain with . should start at a new line if the chain of functions contains more than one call:
val value = otherValue !!
.map { x -> x }
.filter {
val a = true
true
}
.size Note: The parser prohibits the separation of the !! operator from the value it is checking.
Exception : If a functional chain is used inside the branches of a ternary operator, it does not need to be split with newlines.
Valid example :
if (condition) list.map { foo(it) }.filter { bar(it) } else list.drop( 1 )Note: If dot qualified expression is inside condition or passed as an argument - it should be replaced with new variable.
Invalid example :
if (node.treeParent.treeParent?.treeParent.findChildByType( IDENTIFIER ) != null ) {}Valid example :
val grandIdentifier = node
.treeParent
.treeParent
?.treeParent
.findChildByType( IDENTIFIER )
if (grandIdentifier != null ) {}Second valid example :
val grandIdentifier = node.treeParent
.treeParent
?.treeParent
.findChildByType( IDENTIFIER )
if (grandIdentifier != null ) {}= ).( . A brace should be placed immediately after the name without any spaces in declarations or at call sites., ).it ), the newline character should be placed after the opening brace ( { ). The following examples illustrate this rule:Invalid example:
value.map { name -> foo()
bar()
}Valid example:
value.map { name ->
foo()
bar()
}
val someValue = { node : String -> node }대신 :
override fun toString (): String { return " hi " }사용:
override fun toString () = " hi "Valid example:
class Foo ( val a : String ,
b : String ,
val c : String ) {
}
fun foo (
a : String ,
b : String ,
c : String
) {
}If and only if the first parameter is on the same line as an opening parenthesis, all parameters can be horizontally aligned by the first parameter. Otherwise, there should be a line break after an opening parenthesis.
Kotlin 1.4 introduced a trailing comma as an optional feature, so it is generally recommended to place all parameters on a separate line and append trailing comma. It makes the resolving of merge conflicts easier.
Valid example:
fun foo (
a : String ,
b : String ,
) {
}same should be done for function calls/constructor arguments/etc
Kotlin supports trailing commas in the following cases:
Enumerations Value arguments Class properties and parameters Function value parameters Parameters with optional type (including setters) Indexing suffix Lambda parameters when entry Collection literals (in annotations) Type arguments Type parameters Destructuring declarations
Valid example:
class MyFavouriteVeryLongClassHolder :
MyLongHolder < MyFavouriteVeryLongClass >(),
SomeOtherInterface ,
AndAnotherOne { }Reduce unnecessary blank lines and maintain a compact code size. By reducing unnecessary blank lines, you can display more code on one screen, which improves code readability.
init blocks, and objects (see 3.1.2).Valid example:
fun baz () {
doSomething() // No need to add blank lines at the beginning and end of the code block
// ...
}This section describes general rules and recommendations for using spaces in the code.
Follow the recommendations below for using space to separate keywords:
Note: These recommendations are for cases where symbols are located on the same line. However, in some cases, a line break could be used instead of a space.
Separate keywords (such as if , when , for ) from the opening parenthesis with single whitespace. The only exception is the constructor keyword, which should not be separated from the opening parenthesis.
Separate keywords like else or try from the opening brace ( { ) with single whitespace. If else is used in a ternary-style statement without braces, there should be a single space between else and the statement after: if (condition) foo() else bar()
Use a single whitespace before all opening braces ( { ). The only exception is the passing of a lambda as a parameter inside parentheses:
private fun foo ( a : ( Int ) -> Int , b : Int ) {}
foo({x : Int -> x}, 5 ) // no space before '{'where keyword: where T : Type(str: String) -> str.length()Exceptions:
:: ) are written without spaces:Object::toString. ) that stays on the same line with an object name:object.toString()?. 그리고 !! that stay on the same line with an object name:object?.toString().. for creating ranges:1..100 Use spaces after ( , ), ( : ), and ( ; ), except when the symbol is at the end of the line. However, note that this code style prohibits the use of ( ; ) in the middle of a line (see 3.3.2). There should be no whitespaces at the end of a line. The only scenario where there should be no space after a colon is when the colon is used in the annotation to specify a use-site target (for example, @param:JsonProperty ). There should be no spaces before , , : and ; .
Exceptions for spaces and colons:
: is used to separate a type and a supertype, including an anonymous object (after object keyword)Valid example:
abstract class Foo < out T : Any > : IFoo { }
class FooImpl : Foo () {
constructor (x : String ) : this (x) { /* ... */ }
val x = object : IFoo { /* ... */ }
} There should be only one space between the identifier and its type: list: List<String> If the type is nullable, there should be no space before ? .
When using [] operator ( get/set ) there should be no spaces between identifier and [ : someList[0] .
There should be no space between a method or constructor name (both at declaration and at call site) and a parenthesis: foo() {} . Note that this sub-rule is related only to spaces; the rules for whitespaces are described in see 3.6.2. This rule does not prohibit, for example, the following code:
fun foo
(
a : String
) Never put a space after ( , [ , < (when used as a bracket in templates) or before ) , ] , > (when used as a bracket in templates).
There should be no spaces between a prefix/postfix operator (like !! or ++ ) and its operand.
Horizontal alignment refers to aligning code blocks by adding space to the code. Horizontal alignment should not be used because:
Recommendation: Alignment only looks suitable for enum class , where it can be used in table format to improve code readability:
enum class Warnings ( private val id : Int , private val canBeAutoCorrected : Boolean , private val warn : String ) : Rule {
PACKAGE_NAME_MISSING ( 1 , true , " no package name declared in a file " ),
PACKAGE_NAME_INCORRECT_CASE ( 2 , true , " package name should be completely in a lower case " ),
PACKAGE_NAME_INCORRECT_PREFIX ( 3 , false , " package name should start from the company's domain " )
;
}Valid example:
private val nr : Int // no alignment, but looks fine
private var color : Color // no alignmentInvalid example :
private val nr : Int // aligned comment with extra spaces
private val color : Color // alignment for a comment and alignment for identifier nameEnum values are separated by a comma and line break, with ';' placed on the new line.
; on the new line: enum class Warnings {
A ,
B ,
C ,
;
}This will help to resolve conflicts and reduce the number of conflicts during merging pull requests. Also, use trailing comma.
enum class Suit { CLUBS , HEARTS , SPADES , DIAMONDS } val isCelsius = true
val isFahrenheit = falseuse enum class:
enum class TemperatureScale { CELSIUS , FAHRENHEIT }-1, 0, and 1 ; use enums instead. enum class ComparisonResult {
ORDERED_ASCENDING ,
ORDERED_SAME ,
ORDERED_DESCENDING ,
;
}This section describes rules for the declaration of variables.
Each property or variable must be declared on a separate line.
Invalid example :
val n1 : Int ; val n2 : Int Declare local variables close to the point where they are first used to minimize their scope. This will also increase the readability of the code. Local variables are usually initialized during their declaration or immediately after. The member fields of the class should be declared collectively (see Rule 3.1.2 for details on the class structure).
The when statement must have an 'else' branch unless the condition variable is enumerated or a sealed type. Each when statement should contain an else statement group, even if it does not contain any code.
Exception: If 'when' statement of the enum or sealed type contains all enum values, there is no need to have an "else" branch. The compiler can issue a warning when it is missing.
Each annotation applied to a class, method or constructor should be placed on its own line. Consider the following examples:
Valid example :
@MustBeDocumented
@CustomAnnotation
fun getNameIfPresent () { /* ... */ }Valid example :
@CustomAnnotation class Foo {}Valid example :
@MustBeDocumented @CustomAnnotation val loader : DataLoaderBlock comments should be placed at the same indentation level as the surrounding code. See examples below.
Valid example :
class SomeClass {
/*
* This is
* okay
*/
fun foo () {}
} Note : Use /*...*/ block comments to enable automatic formatting by IDEs.
This section contains recommendations regarding modifiers and constant values.
If a declaration has multiple modifiers, always follow the proper sequence. Valid sequence:
public / internal / protected / private
expect / actual
final / open / abstract / sealed / const
external
override
lateinit
tailrec
crossinline
vararg
suspend
inner
out
enum / annotation
companion
inline / noinline
reified
infix
operator
dataAn underscore character should separate long numerical values. Note: Using underscores simplifies reading and helps to find errors in numeric constants.
val oneMillion = 1_000_000
val creditCardNumber = 1234_5678_9012_3456L
val socialSecurityNumber = 999_99_9999L
val hexBytes = 0xFF_EC_DE_5E
val bytes = 0b11010010_01101001_10010100_10010010 Prefer defining constants with clear names describing what the magic number means. Valid example :
class Person () {
fun isAdult ( age : Int ): Boolean = age >= majority
companion object {
private const val majority = 18
}
}Invalid example :
class Person () {
fun isAdult ( age : Int ): Boolean = age >= 18
}This section describes the general rules of using strings.
String concatenation is prohibited if the string can fit on one line. Use raw strings and string templates instead. Kotlin has significantly improved the use of Strings: String templates, Raw strings. Therefore, compared to using explicit concatenation, code looks much better when proper Kotlin strings are used for short lines, and you do not need to split them with newline characters.
Invalid example :
val myStr = " Super string "
val value = myStr + " concatenated "Valid example :
val myStr = " Super string "
val value = " $myStr concatenated " Redundant curly braces in string templates
If there is only one variable in a string template, there is no need to use such a template. Use this variable directly. Invalid example :
val someString = " ${myArgument} ${myArgument.foo()} "Valid example :
val someString = " $myArgument ${myArgument.foo()} "Redundant string template
In case a string template contains only one variable - there is no need to use the string template. Use this variable directly.
Invalid example :
val someString = " $myArgument "Valid example :
val someString = myArgumentThis section describes the general rules related to the сonditional statements.
The nested if-statements, when possible, should be collapsed into a single one by concatenating their conditions with the infix operator &&.
This improves the readability by reducing the number of the nested language constructs.
Invalid example :
if (cond1) {
if (cond2) {
doSomething()
}
}Valid example :
if (cond1 && cond2) {
doSomething()
}Invalid example :
if (cond1) {
if (cond2 || cond3) {
doSomething()
}
}Valid example :
if (cond1 && (cond2 || cond3)) {
doSomething()
}Too complex conditions should be simplified according to boolean algebra rules, if it is possible. The following rules are considered when simplifying an expression:
foo() || false -> foo() )!(!a) -> a )a && b && a -> a && b )a || (a && b) -> a )a && (a || b) -> a )!(a || b) -> !a && !b )Valid example
if (condition1 && condition2) {
foo()
}Invalid example
if (condition1 && condition2 && condition1) {
foo()
}This section is dedicated to the rules and recommendations for using variables and types in your code.
The rules of using variables are explained in the below topics.
Floating-point numbers provide a good approximation over a wide range of values, but they cannot produce accurate results in some cases. Binary floating-point numbers are unsuitable for precise calculations because it is impossible to represent 0.1 or any other negative power of 10 in a binary representation with a finite length.
The following code example seems to be obvious:
val myValue = 2.0 - 1.1
println (myValue) However, it will print the following value: 0.8999999999999999
Therefore, for precise calculations (for example, in finance or exact sciences), using such types as Int , Long , BigDecimal are recommended. The BigDecimal type should serve as a good choice.
Invalid example : Float values containing more than six or seven decimal numbers will be rounded.
val eFloat = 2.7182818284f // Float, will be rounded to 2.7182817Valid example : (when precise calculations are needed):
val income = BigDecimal ( " 2.0 " )
val expense = BigDecimal ( " 1.1 " )
println (income.subtract(expense)) // you will obtain 0.9 here Numeric float type values should not be directly compared with the equality operator (==) or other methods, such as compareTo() and equals() . Since floating-point numbers involve precision problems in computer representation, it is better to use BigDecimal as recommended in Rule 4.1.1 to make accurate computations and comparisons. The following code describes these problems.
Invalid example :
val f1 = 1.0f - 0.9f
val f2 = 0.9f - 0.8f
if (f1 == f2) {
println ( " Expected to enter here " )
} else {
println ( " But this block will be reached " )
}
val flt1 = f1;
val flt2 = f2;
if (flt1.equals(flt2)) {
println ( " Expected to enter here " )
} else {
println ( " But this block will be reached " )
}Valid example :
val foo = 1.03f
val bar = 0.42f
if (abs(foo - bar) > 1e - 6f ) {
println ( " Ok " )
} else {
println ( " Not " )
} Variables with the val modifier are immutable (read-only). Using val variables instead of var variables increases code robustness and readability. This is because var variables can be reassigned several times in the business logic. However, in some scenarios with loops or accumulators, only var s are permitted.
This section provides recommendations for using types.
The Kotlin compiler has introduced Smart Casts that help reduce the size of code.
Invalid example :
if (x is String ) {
print ((x as String ).length) // x was already automatically cast to String - no need to use 'as' keyword here
}Valid example :
if (x is String ) {
print (x.length) // x was already automatically cast to String - no need to use 'as' keyword here
} Also, Kotlin 1.3 introduced Contracts that provide enhanced logic for smart-cast. Contracts are used and are very stable in stdlib , for example:
fun bar ( x : String? ) {
if ( ! x.isNullOrEmpty()) {
println ( " length of ' $x ' is ${x.length} " ) // smartcasted to not-null
}
}Smart cast and contracts are a better choice because they reduce boilerplate code and features forced type conversion.
Invalid example :
fun String?. isNotNull (): Boolean = this != null
fun foo ( s : String? ) {
if (s.isNotNull()) s !! .length // No smartcast here and !! operator is used
}Valid example :
fun foo ( s : String? ) {
if (s.isNotNull()) s.length // We have used a method with contract from stdlib that helped compiler to execute smart cast
} Type aliases provide alternative names for existing types. If the type name is too long, you can replace it with a shorter name, which helps to shorten long generic types. For example, code looks much more readable if you introduce a typealias instead of a long chain of nested generic types. We recommend using a typealias if the type contains more than two nested generic types and is longer than 25 chars .
Invalid example :
val b : MutableMap < String , MutableList < String >>Valid example :
typealias FileTable = MutableMap < String , MutableList < String >>
val b : FileTableYou can also provide additional aliases for function (lambda-like) types:
typealias MyHandler = ( Int , String , Any ) -> Unit
typealias Predicate < T > = ( T ) -> BooleanKotlin is declared as a null-safe programming language. However, to achieve compatibility with Java, it still supports nullable types.
To avoid NullPointerException and help the compiler prevent Null Pointer Exceptions, avoid using nullable types (with ? symbol).
Invalid example :
val a : Int? = 0Valid example :
val a : Int = 0 Nevertheless, when using Java libraries extensively, you have to use nullable types and enrich the code with !! 그리고 ? symbols. Avoid using nullable types for Kotlin stdlib (declared in official documentation). Try to use initializers for empty collections. For example, if you want to initialize a list instead of null , use emptyList() .
Invalid example :
val a : List < Int > ? = nullValid example :
val a : List < Int > = emptyList()Like in Java, classes in Kotlin may have type parameters. To create an instance of such a class, we typically need to provide type arguments:
val myVariable : Map < Int , String > = emptyMap< Int , String >()However, the compiler can inherit type parameters from the r-value (value assigned to a variable). Therefore, it will not force users to declare the type explicitly. These declarations are not recommended because programmers would need to find the return value and understand the variable type by looking at the method.
Invalid example :
val myVariable = emptyMap< Int , String >()Valid example :
val myVariable : Map < Int , String > = emptyMap() Try to avoid explicit null checks (explicit comparison with null ) Kotlin is declared as Null-safe language. However, Kotlin architects wanted Kotlin to be fully compatible with Java; that's why the null keyword was also introduced in Kotlin.
There are several code-structures that can be used in Kotlin to avoid null-checks. For example: ?: , .let {} , .also {} , etc
Invalid example:
// example 1
var myVar : Int? = null
if (myVar == null ) {
println ( " null " )
return
}
// example 2
if (myVar != null ) {
println ( " not null " )
return
}
// example 3
val anotherVal = if (myVar != null ) {
println ( " not null " )
1
} else {
2
}
// example 4
if (myVar == null ) {
println ( " null " )
} else {
println ( " not null " )
}Valid example:
// example 1
var myVar : Int? = null
myVar ? : run {
println ( " null " )
return
}
// example 2
myVar?. let {
println ( " not null " )
return
}
// example 3
val anotherVal = myVar?. also {
println ( " not null " )
1
} ? : 2
// example 4
myVar?. let {
println ( " not null " )
} ? : run { println ( " null " ) }Exceptions:
In the case of complex expressions, such as multiple else-if structures or long conditional statements, there is common sense to use explicit comparison with null .
Valid examples:
if (myVar != null ) {
println ( " not null " )
} else if (anotherCondition) {
println ( " Other condition " )
} if (myVar == null || otherValue == 5 && isValid) {} Please also note, that instead of using require(a != null) with a not null check - you should use a special Kotlin function called requireNotNull(a) .
This section describes the rules of using functions in your code.
Developers can write clean code by gaining knowledge of how to build design patterns and avoid code smells. You should utilize this approach, along with functional style, when writing Kotlin code. The concepts behind functional style are as follows: Functions are the smallest unit of combinable and reusable code. They should have clean logic, high cohesion , and low coupling to organize the code effectively. The code in functions should be simple and not conceal the author's original intentions.
Additionally, it should have a clean abstraction, and control statements should be used straightforwardly. The side effects (code that does not affect a function's return value but affects global/object instance variables) should not be used for state changes of an object. The only exceptions to this are state machines.
Kotlin is designed to support and encourage functional programming, featuring the corresponding built-in mechanisms. Also, it supports standard collections and sequences feature methods that enable functional programming (for example, apply , with , let , and run ), Kotlin Higher-Order functions, function types, lambdas, and default function arguments. As previously discussed, Kotlin supports and encourages the use of immutable types, which in turn motivates programmers to write pure functions that avoid side effects and have a corresponding output for specific input. The pipeline data flow for the pure function comprises a functional paradigm. It is easy to implement concurrent programming when you have chains of function calls, where each step features the following characteristics:
There can be only one side effect in this data stream, which can be placed only at the end of the execution queue.
The function should be displayable on one screen and only implement one certain logic. If a function is too long, it often means complex and could be split or simplified. Functions should consist of 30 lines (non-empty and non-comment) in total.
Exception: Some functions that implement complex algorithms may exceed 30 lines due to aggregation and comprehensiveness. Linter warnings for such functions can be suppressed .
Even if a long function works well, new problems or bugs may appear due to the function's complex logic once it is modified by someone else. Therefore, it is recommended to split such functions into several separate and shorter functions that are easier to manage. This approach will enable other programmers to read and modify the code properly.
The nesting depth of a function's code block is the depth of mutual inclusion between the code control blocks in the function (for example: if, for, while, and when). Each nesting level will increase the amount of effort needed to read the code because you need to remember the current "stack" (for example, entering conditional statements and loops). Exception: The nesting levels of the lambda expressions, local classes, and anonymous classes in functions are calculated based on the innermost function. The nesting levels of enclosing methods are not accumulated. Functional decomposition should be implemented to avoid confusion for the developer who reads the code. This will help the reader switch between contexts.
Nested functions create a more complex function context, thereby confusing readers. With nested functions, the visibility context may not be evident to the code reader.
Invalid example :
fun foo () {
fun nested (): String {
return " String from nested function "
}
println ( " Nested Output: ${nested()} " )
}Don't use negated function calls if it can be replaced with negated version of this function
Invalid example :
fun foo () {
val list = listOf ( 1 , 2 , 3 )
if ( ! list.isEmpty()) {
// Some cool logic
}
}Valid example :
fun foo () {
val list = listOf ( 1 , 2 , 3 )
if (list.isNotEmpty()) {
// Some cool logic
}
}The rules for using function arguments are described in the below topics.
With such notation, it is easier to use curly brackets, leading to better code readability.
Valid example :
// declaration
fun myFoo ( someArg : Int , myLambda : () -> Unit ) {
// ...
}
// usage
myFoo( 1 ) {
println ( " hey " )
}A long argument list is a code smell that leads to less reliable code. It is recommended to reduce the number of parameters. Having more than five parameters leads to difficulties in maintenance and conflicts merging. If parameter groups appear in different functions multiple times, these parameters are closely related and can be encapsulated into a single Data Class. It is recommended that you use Data Classes and Maps to unify these function arguments.
In Java, default values for function arguments are prohibited. That is why the function should be overloaded when you need to create a function with fewer arguments. In Kotlin, you can use default arguments instead.
Invalid example :
private fun foo ( arg : Int ) {
// ...
}
private fun foo () {
// ...
}Valid example :
private fun foo ( arg : Int = 0) {
// ...
} Try to avoid using runBlocking in asynchronous code
Invalid example :
GlobalScope .async {
runBlocking {
count ++
}
}The lambda without parameters shouldn't be too long. If a lambda is too long, it can confuse the user. Lambda without parameters should consist of 10 lines (non-empty and non-comment) in total.
Expressions with unnecessary, custom labels generally increase complexity and worsen the maintainability of the code.
Invalid example :
run lab@ {
list.forEach {
return @lab
}
}Valid example :
list.forEachIndexed { index, i ->
return @forEachIndexed
}
lab@ for (i : Int in q) {
for (j : Int in q) {
println (i)
break @lab
}
}This section describes the rules of denoting classes in your code.
When a class has a single constructor, it should be defined as a primary constructor in the declaration of the class. If the class contains only one explicit constructor, it should be converted to a primary constructor.
Invalid example :
class Test {
var a : Int
constructor (a : Int ) {
this .a = a
}
}Valid example :
class Test ( var a : Int ) {
// ...
}
// in case of any annotations or modifiers used on a constructor:
class Test private constructor( var a : Int ) {
// ...
} Some people say that the data class is a code smell. However, if you need to use it (which makes your code more simple), you can utilize the Kotlin data class . The main purpose of this class is to hold data, but also data class will automatically generate several useful methods:
Therefore, instead of using normal classes:
class Test {
var a : Int = 0
get() = field
set(value : Int ) { field = value}
}
class Test {
var a : Int = 0
var b : Int = 0
constructor (a : Int , b : Int ) {
this .a = a
this .b = b
}
}
// or
class Test ( var a : Int = 0 , var b : Int = 0 )
// or
class Test () {
var a : Int = 0
var b : Int = 0
}prefer data classes:
data class Test1 ( var a : Int = 0 , var b : Int = 0 )Exception 1 : Note that data classes cannot be abstract, open, sealed, or inner; that is why these types of classes cannot be changed to a data class.
Exception 2 : No need to convert a class to a data class if this class extends some other class or implements an interface.
The primary constructor is a part of the class header; it is placed after the class name and type parameters (optional) but can be omitted if it is not used.
Invalid example :
// simple case that does not need a primary constructor
class Test () {
var a : Int = 0
var b : Int = 0
}
// empty primary constructor is not needed here
// it can be replaced with a primary contructor with one argument or removed
class Test () {
var a = " Property "
init {
println ( " some init " )
}
constructor (a : String ) : this () {
this .a = a
}
}Valid example :
// the good example here is a data class; this example also shows that you should get rid of braces for the primary constructor
class Test {
var a : Int = 0
var b : Int = 0
} Several init blocks are redundant and generally should not be used in your class. The primary constructor cannot contain any code. That is why Kotlin has introduced init blocks. These blocks store the code to be run during the class initialization. Kotlin allows writing multiple initialization blocks executed in the same order as they appear in the class body. Even when you follow (rule 3.2)[#r3.2], this makes your code less readable as the programmer needs to keep in mind all init blocks and trace the execution of the code. Therefore, you should try to use a single init block to reduce the code's complexity. If you need to do some logging or make some calculations before the class property assignment, you can use powerful functional programming. This will reduce the possibility of the error if your init blocks' order is accidentally changed and make the code logic more coupled. It is always enough to use one init block to implement your idea in Kotlin.
Invalid example :
class YourClass ( var name : String ) {
init {
println ( " First initializer block that prints ${name} " )
}
val property = " Property: ${name.length} " . also (::println)
init {
println ( " Second initializer block that prints ${name.length} " )
}
}Valid example :
class YourClass ( var name : String ) {
init {
println ( " First initializer block that prints ${name} " )
}
val property = " Property: ${name.length} " . also { prop ->
println (prop)
println ( " Second initializer block that prints ${name.length} " )
}
} The init block was not added to Kotlin to help you initialize your properties; it is needed for more complex tasks. Therefore if the init block contains only assignments of variables - move it directly to properties to be correctly initialized near the declaration. In some cases, this rule can be in clash with 6.1.1, but that should not stop you.
Invalid example :
class A ( baseUrl : String ) {
private val customUrl : String
init {
customUrl = " $baseUrl /myUrl "
}
}Valid example :
class A ( baseUrl : String ) {
private val customUrl = " $baseUrl /myUrl "
}The explicit supertype qualification should not be used if there is no clash between called methods. This rule is applicable to both interfaces and classes.
Invalid example :
open class Rectangle {
open fun draw () { /* ... */ }
}
class Square () : Rectangle() {
override fun draw () {
super < Rectangle >.draw() // no need in super<Rectangle> here
}
} Abstract classes are used to force a developer to implement some of its parts in their inheritors. When the abstract class has no abstract methods, it was set abstract incorrectly and can be converted to a regular class.
Invalid example :
abstract class NotAbstract {
fun foo () {}
fun test () {}
}Valid example :
abstract class NotAbstract {
abstract fun foo ()
fun test () {}
}
// OR
class NotAbstract {
fun foo () {}
fun test () {}
}Kotlin has a mechanism of backing properties. In some cases, implicit backing is not enough and it should be done explicitly:
private var _table : Map < String , Int > ? = null
val table : Map < String , Int >
get() {
if ( _table == null ) {
_table = HashMap () // Type parameters are inferred
}
return _table ? : throw AssertionError ( " Set to null by another thread " )
} In this case, the name of the backing property ( _table ) should be the same as the name of the real property ( table ) but should have an underscore ( _ ) prefix. It is one of the exceptions from the identifier names rule
Kotlin has a perfect mechanism of properties. Kotlin compiler automatically generates get and set methods for properties and can override them.
Invalid example:
class A {
var size : Int = 0
set(value) {
println ( " Side effect " )
field = value
}
// user of this class does not expect calling A.size receive size * 2
get() = field * 2
} From the callee code, these methods look like access to this property: A().isEmpty = true for setter and A().isEmpty for getter.
However, when get and set are overridden, it isn't very clear for a developer who uses this particular class. The developer expects to get the property value but receives some unknown value and some extra side-effect hidden by the custom getter/setter. Use extra functions instead to avoid confusion.
Valid example :
class A {
var size : Int = 0
fun initSize ( value : Int ) {
// some custom logic
}
// this will not confuse developer and he will get exactly what he expects
fun goodNameThatDescribesThisGetter () = this .size * 2
} Exception: Private setters are only exceptions that are not prohibited by this rule.
If you ignored recommendation 6.1.8, be careful with using the name of the property in your custom getter/setter as it can accidentally cause a recursive call and a StackOverflow Error . Use the field keyword instead.
Invalid example (very bad) :
var isEmpty : Boolean
set(value) {
println ( " Side effect " )
isEmpty = value
}
get() = isEmptyIn Java, trivial getters - are the getters that are just returning the field value. Trivial setters - are merely setting the field with a value without any transformation. However, in Kotlin, trivial getters/setters are generated by default. There is no need to use it explicitly for all types of data structures in Kotlin.
Invalid example :
class A {
var a : Int = 0
get() = field
set(value : Int ) { field = value }
//
}Valid example :
class A {
var a : Int = 0
get() = field
set(value : Int ) { field = value }
//
} In Java, before functional programming became popular, many classes from common libraries used the configuration paradigm. To use these classes, you had to create an object with the constructor with 0-2 arguments and set the fields needed to run the object. In Kotlin, to reduce the number of dummy code line and to group objects apply extension was added:
Invalid example :
class HttpClient ( var name : String ) {
var url : String = " "
var port : String = " "
var timeout = 0
fun doRequest () {}
}
fun main () {
val httpClient = HttpClient ( " myConnection " )
httpClient.url = " http://example.com "
httpClient.port = " 8080 "
httpClient.timeout = 100
httpCLient.doRequest()
}
Valid example :
class HttpClient ( var name : String ) {
var url : String = " "
var port : String = " "
var timeout = 0
fun doRequest () {}
}
fun main () {
val httpClient = HttpClient ( " myConnection " )
. apply {
url = " http://example.com "
port = " 8080 "
timeout = 100
}
httpClient.doRequest()
}If a class has only one immutable property, then it can be converted to the inline class.
Sometimes it is necessary for business logic to create a wrapper around some type. However, it introduces runtime overhead due to additional heap allocations. Moreover, if the wrapped type is primitive, the performance hit is terrible, because primitive types are usually heavily optimized by the runtime, while their wrappers don't get any special treatment.
Invalid example :
class Password {
val value : String
}Valid example :
inline class Password ( val value : String )This section describes the rules of using extension functions in your code.
Extension functions is a killer-feature in Kotlin. It gives you a chance to extend classes that were already implemented in external libraries and helps you to make classes less heavy. Extension functions are resolved statically.
It is recommended that for classes, the non-tightly coupled functions, which are rarely used in the class, should be implemented as extension functions where possible. They should be implemented in the same class/file where they are used. This is a non-deterministic rule, so the code cannot be checked or fixed automatically by a static analyzer.
You should avoid declaring extension functions with the same name and signature if their receivers are base and inheritor classes (possible_bug), as extension functions are resolved statically. There could be a situation when a developer implements two extension functions: one is for the base class and another for the inheritor. This can lead to an issue when an incorrect method is used.
Invalid example :
open class A
class B : A ()
// two extension functions with the same signature
fun A. foo () = " A "
fun B. foo () = " B "
fun printClassName ( s : A ) { println (s.foo()) }
// this call will run foo() method from the base class A, but
// programmer can expect to run foo() from the class inheritor B
fun main () { printClassName( B ()) }You should not use extension functions for the class in the same file, where it is defined.
Invalid example :
class SomeClass {
}
fun SomeClass. deleteAllSpaces () {
}You should not use property length with operation - 1, you can change this to lastIndex
Invalid example :
val A = " name "
val B = A .length - 1
val C = A [ A .length - 1 ]Valid example :
val A = " name "
val B = A .lastIndex
val C = A [ A .lastIndex] An Interface in Kotlin can contain declarations of abstract methods, as well as method implementations. What makes them different from abstract classes is that interfaces cannot store state. They can have properties, but these need to be abstract or to provide accessor implementations.
Kotlin's interfaces can define attributes and functions. In Kotlin and Java, the interface is the main presentation means of application programming interface (API) design and should take precedence over the use of (abstract) classes.
This section describes the rules of using objects in code.
Avoid using utility classes/objects; use extensions instead. As described in 6.2 Extension functions, using extension functions is a powerful method. This enables you to avoid unnecessary complexity and class/object wrapping and use top-level functions instead.
Invalid example :
object StringUtil {
fun stringInfo ( myString : String ): Int {
return myString.count{ " something " .contains(it) }
}
}
StringUtil .stringInfo( " myStr " )Valid example :
fun String. stringInfo (): Int {
return this .count{ " something " .contains(it) }
}
" myStr " .stringInfo()Kotlin's objects are extremely useful when you need to implement some interface from an external library that does not have any state. There is no need to use classes for such structures.
Valid example :
interface I {
fun foo()
}
object O: I {
override fun foo() {}
}
This section describes general rules for .kts files
It is still recommended wrapping logic inside functions and avoid using top-level statements for function calls or wrapping blocks of code in top-level scope functions like run .
Valid example :
run {
// some code
}
fun foo() {
}
