[Kotlin Docs] Coding conventions

 

본 글은 https://kotlinlang.org/docs/home.html 를 기반으로 작성자 마음대로 번역한 글입니다.
오역 & 의역이 빈번하며 모든 질문 및 태클 환영합니다!
2022-01-17 기준으로 작성되었습니다.

---

Configure style in IDE

코틀린을 위한 인기있는 두 IDE - IntelliJ IDEA↗와 Android Studio↗는 코드 스타일링에 대한 강력한 지원을 제공합니다. 지정된 코드 스타일에 맞게 코드를 자동으로 포맷하도록 구성할 수 있습니다.

 

- Apply the style guide

1. Settings/Preferences | Editor | Code Style | Kotlin 으로 이동
2. Set from.... 클릭
3. Kotlin style guide 선택

 

- Verify that your code follows the style guide

1. Settings/Preferences | Editor | Inspections | Kotlin 으로 이동
2. Kotlin | Style issues 열기
3. File is not formatted according to project settings 설정 켜기. 스타일 가이드에 설명된 다른 문제(예: 명명 규칙)를 확인하는 추가 검사는 기본적으로 사용하도록 설정되어 있습니다.

 

---

Source code organization

- Directory structure

순수한 코틀린 프로젝트에서, 권장 디렉토리 구조는 root 패키지가 생략된 패키지 구조를 따릅니다.
예를 들어, 프로젝트의 모든 코드가 org.example.kotlin 과 그 하위 패키지에 있다면 org.example.kotlin 이 포함된 파일은 소스 루트 아래에 위치해야 하며 org.example.kotlin.network.socket의 파일은 network/socket의 하위 디렉토리에 존재해야 합니다.

JVM : 코틀린과 자바가 함께 사용되는 프로젝트에서 코틀린 소스 파일은 자바 소스 파일과 같은 소스 root에 있어야 하며 동일한 디렉토리 구조를 따라야 합니다. 각 파일은 각 패키지와 일치하는 디렉토리에 있어야 합니다.

 

- Source file names

코틀린 파일에 단일 클래스(관련 최상위 선언 포함)가 포함되어 있는 경우, 파일은 클래스의 이름과 동일한 이름을 갖고 .kt 확장자가 추가되어야합니다. 파일이 여러 클래스나 하나의 최상위 선언을 포함한 경우, 파일에 포함된 내용을 설명하는 이름으로 파일의 이름을 지정해야 합니다. ProcessDeclarations.kt와 같이, 첫 글자가 대문자인 upper camel case↗ (aka. Pascal case) 를 사용해야합니다.

 

파일의 이름은 내부의 코드의 동작을 잘 설명하여야 합니다. 그러므로 Util과 같은 의미 없는 단어의 사용을 피해야합니다.

 

- Source file organization

하나의 동일한 코틀린 소스 파일에 여러개의 선언(클래스, 최상위 함수 혹은 프로퍼티)를 넣는 것은 서로 의미상 밀접하게 연관되어 있고 수백줄을 넘지 않을 때만 권장됩니다.

 

특히나, 어떤 클래스의 모든 클라이언트와 연결되어 있는 extension functions을 작성할 때에는 클래스와 같은 파일에 두십시오. 특정 클라이언트만을 위한 extension functions를 작성한다면 클라이언트의 코드 옆에 두십시오. 어떤 클래스의 모든 extension를 넣기 위해 파일을 생성하는 것을 피하십시오.

 

- Class layout

클래스의 내용은 다음과 같은 순서를 따라야 합니다.

1. 프로퍼티 선언 및 초기화 블럭
2. 보조 생성자
3. 메소드 선언
4. Companion object

메소드를 알파벳이나 가시성 순으로 정렬하거나 일반 메소드와 extension 메소드를 구분하지 마십시오. 대신, 연관된 내용을 함께 두고 누군가가 클래스를 위에서 아래로 읽을 때 어떤 로직인지 잘 파악할 수 있도록 하세요. 정렬 방식을 선택하여 일관되게 적용하십시오.

 

해당 클래스를 사용하는 코드 옆에 중첩 클래스를 배치하십시오.
클래스가 외부 사용 목적이며 내부에서 참조하지 않는다면, companion object의 뒤쪽 맨 끝에 두십시오.

 

- Interface implementation layout

인터페이스를 구현하는 경우, 구현 멤버를 인터페이스의 멤버와 같은 순서로 유지합니다. (필요하다면, 구현을 위해 추가적인 별개의 메소드를 작성하십시오)

 

- Overload layout

오버로드들을 항상 클래스에서 나란히 배치하십시오.

 

---

Naming rules

코틀린에서의 패키지와 클래스 네이밍 규칙은 단순합니다.

• 패키지의 이름은 항상 underscores가 쓰이지 않은 lowercase로 작성합니다. (org.example.project). 여러 단어의 이름은 권장되지 않으나, 필요하다면 연결하거나 camel case를 사용할 수 있습니다. (org.example.myProject).
• 클래스나 object의 이름은 대문자로 시작하며 camel case를 따라야 합니다.

 

 

- Function names

함수의 이름과, 프로퍼티 그리고 지역변수는 소문자로 시작하며 underscores 없이 camel case를 사용합니다.

 

 

예외 : 클래스의 인스턴스를 만드는데 사용되는 팩토리 함수는 abstract return type과 같은 이름을 가질 수 있습니다.

 

 

- Names for test methods

테스트에서(만), backtick( ` ) 내부에 공백이 있는 메소드 이름을 사용할 수 있습니다. 이러한 메소드 이름은 안드로이드 런타임에서 지원되지 않습니다. 테스트 코드에서는 메소드 이름 내의 Underscores도 허용됩니다.

 

 

- Property names

상수의 이름(const로 표시된 프로퍼티, 커스텀 get 함수를 갖지 않는 깊이 불변의 최상위 혹은 val 프로퍼티)은 대문자와 underscore-separated (screaming scake case↗) 이름을 사용해야 합니다.

 

 

동작 또는 가변 데이터를 가진 오브젝트를 유지하는 최상위 또는 객체 프로퍼티의 이름은 camel case를 사용해야합니다.

 

 

싱글톤 오브젝트를 참조하고 있는 프로퍼티의 이름은 object 선언과 같은 네이밍 스타일을 사용할 수 있습니다.

 

 

enum 상수에서는, 사용에 따라 대문자와 underscore-separated names (screaming scake case↗) (enum class Color {RED, GREEN})이나 upper camel case를 사용할 수 있습니다.

 

- Names for backing properties

클래스가 개념적으로는 동일하지만 하나는 public API의 일부이고 다른 하나는 상세 구현일 경우, private 프로퍼티의 이름 접두어로 underscore를 사용하십시오.

 

 

- Choose good names

클래스의 이름은 일반적으로 그 클래스가 무엇인지 설명하는 명사 혹은 명사구입니다. (List, PersonReader)

 

메소드의 이름은 메소드가 무슨 일을 하는지 알려주는 동사 혹은 동사구입니다. (close, readPersons) 또한 객체를 변경하는지 새로운 객체를 반환하는지를 알 수 있어야 합니다.
예를 들어 sort는 컬렉션을 정렬하는 것이고, sorted는 정렬된 컬렉션의 복사본을 반환하는 것입니다.

이름은 엔티티의 목적이 무엇인지 명확해야 합니다. 따라서 의미없는 단어(Manager, Wrapper)의 사용을 피하는 것이 좋습니다.

선언하려는 이름의 일부가 축약어인 경우, 두 글자인 경우에는 대문자로 (IOStream), 더 긴 경우에는 첫 글자만 대문자로 표기합니다 (XmlFormatter, HttpInputStream).

 

---

Formatting

- indentation

들여쓰기를 하려면 탭이 아닌 4개의 스페이스를 사용하세요.

 

중괄호의 경우, 여는 중괄호는 구조가 시작하는 줄의 마지막에,
닫는 중괄호는 구조의 시작과 수평으로 정렬되는 곳에 넣으세요.

 

 

코틀린에서 세미콜론은 옵션이기 때문에 줄바꿈은 중요합니다. Java 스타일의 괄호를 기반으로 하므로, 다른 포맷 스타일을 사용할 경우 잘못된 동작이 일어날 수 있습니다.

 

- Horizontal whitespace

• 이항 연산자 주변에는 공백을 두십시오. (a + b).
  예외 : "범위" 연산자 주변에는 공백이 없어야 합니다. (0..i)
• 단항 연산자 (a++) 주위에 공백을 두지 마십시오.
• 제어 흐름의 키워드 (if, when, for, while) 과 대응하는 괄호에는 공백을 두십시오.
• 기본 생성자 선언 및 메소드 선언이나 사용괄호 직전에는 공백을 두지 마십시오.
• (, [, 이후나 ], ) 이전에는 공백을 두지 마십시오.
• .이나 ?. 주변에 공백을 두지 마십시오. foo.bar().filter { it > 2}.joinToString(), foo?.bar()
• // 이후에 공백을 두십시오. (//는 주석입니다.)
• 특정 타입 파라미터를 위해 사용되는 꺽쇠 주변에 공백을 두지 마십시오.
  class Map<K, V> { ... }
• :: 주변에 공백을 두지 마십시오. (Foo::class, String::length)
• nullable 타입을 표현하는 ? 이전에 공백을 두지 마십시오. (String?)

기본적으로 어떤 종류의 수평 정렬도 피하십시오.
식별자를 다른 길이의 이름으로 변경하는 것이 선언이나 사용의 포맷에 영향을 주어서는 안됩니다.

 

- Colon

다음 경우에는 : 주변에 공백을 사용하십시오.

• type과 supertype을 구분하는데 사용되는 경우
• 슈퍼클래스 생성자 또는 같은 클래스의 다른 생성자에 위임할 때
• object 키워드 이후

선언과 타입 사이에 :를 사용하는 경우 그 전에 공백을 두지 마십시오.
: 이후에는 항상 공백을 두십시오.

 

 

- Class headers

기본 생성자의 파라미터가 적은경우 한줄에 쓸 수 있습니다.

 

 

헤더가 긴 클래스의 경우, 각각의 기본 생성자 파라미터는 들여쓰기와 함께 각 줄에 쓰여야 합니다.
또한, 닫는 괄호는 새로운 줄에 쓰여야 합니다. 만약 상속을 받는다면, 슈퍼클래스의 생성자 호출이나 구현하는 인터페이스의 리스트는 괄호와 같은 줄에 있어야 합니다.

 

 

여러 인터페이스의 경우, 슈퍼클래스 생성자는 맨 처음에, 각 인터페이스는 다른 줄에 위치해야 합니다.

 

 

슈퍼타입의 길이가 긴 클래스의 경우, 콜론 이후에 줄을 바꾸고 모든 슈퍼타입의 이름을 수평적으로 정렬시킵니다.

 

 

클래스의 헤더가 긴 경우 클래스 헤더와 본문을 명확하게 분리하기 위해서 헤더 다음에 줄을 바꾸거나 (위의 예시처럼) 중괄호를 다음 줄에 배치하십시오.

 

 

생성자 파라미터에는 기본 들여쓰기 (4 spaces)를 사용하십시오.
이렇게 하면 기본 생성자에서 선언된 프로퍼티와 본문에 선언된 프로퍼티의 들여쓰기가 같게 됩니다.

 

- Modifiers order

선언이 여러개의 제한자를 가지고 있으다면 다음 순서에 맞게 넣으십시오.

 

 

모든 어노테이션은 제한자 앞에 두십시오.

 

 

라이브러리에서 작업하는 것이 아닌 이상, 불필요한 제한자를 생략하십시오 (ex. public)

 

- Annotations

어노테이션은 선언 이전의 분리된 줄에 같은 들여쓰기로 넣으십시오.

 

 

매개변수가 없는 어노테이션은 같은 줄에 위치시키십시오.

 

 

매개변수가 없는 하나의 어노테이션은 선언과 같은 줄에 위치시킬 수 있습니다.

 

 

- File annotations

파일 어노테이션은 package 이전, 파일 주석 이후에 위치하며 package와 빈 줄로 구분됩니다. (패키지가 아닌 파일을 대상으로 한다는 것을 강조하기 위함)

 

 

- Functions

함수의 시그니쳐가 한 줄에 맞지 않는 경우 다음 구문을 따르십시오.

 

 

함수의 파라미터에는 기본 들여쓰기 (4 spaces)를 사용하십시오. 이것은 기본 생성자 파라미터와 일관성을 유지합니다.

 

본문에 하나의 표현식만 존재하는 함수는 표현식을 사용하십시오.

 

 

- Expression bodies

표현식을 가진 함수가 같은 줄에 선언되지 않는다면, =를 첫번째 줄에 두고 그 다음 줄에 표현식을 들여쓰기 하십시오.

 

 

- Properties

아주 간단한 read-only 프로퍼티는 한 줄에 적는 것이 좋습니다.

 

 

더 복잡한 프로퍼티의 경우는 get과 set 키워드는 분리된 줄에 적으십시오.

 

 

초기화되는 프로퍼티의 경우, 초기화가 긴 경우 =를 첫번째 줄에 두고 그 다음 줄에 표현식을 들여쓰기 하십시오.

 

 

- Control flow statements

if 또는 when의 조건이 여러줄이라면, 본문에 항상 중괄호를 사용하십시오. 조건의 두번째 줄부터는 문장이 시작하는 곳은 4 spaces의 들여쓰기가 있어야 합니다. 조건의 닫는 괄호는 여는 중괄호와 함께 다른 줄에 사용하십시오.

 

 

이것은 조건과 본문을 정렬하는데 도움이 됩니다.

 

else, catch, finally 뿐만아니라 do-while loop의 while키워드는 이전 중괄호와 같은 줄에 있어야 합니다.

 

 

when구문에서 branch가 한 줄을 넘어간다면, 인접한 블럭과 빈 줄로 구분하는 것을 염두하십시오.

 

 

짧은 branch는 중괄호 없이 조건과 같은 줄에 두십시오.

 

 

- Method calls

긴 매개변수의 리스트는 여는 괄호 이후에 줄을 바꿉니다. 4 spaces로 매개변수를 들여쓰기 하십시오. 연관된 매개변수들을 같은 줄에 그룹화 하십시오.

 

 

매개변수의 이름과 값을 나누는 = 주변에 공백을 두십시오.

 

- Wrap chained calls

연속된 호출의 경우, .와 ?.를 다음줄에 하나의 들여쓰기와 함께 적으십시오.

 

 

체인의 첫번째 호출은 일반적으로 줄을 바꾸지만, 가독성을 위해 생략해도 괜찮습니다.

 

- Lambdas

람다식에서, 중괄호 주변과 파라미터를 본문과 구별하는 화살표 주변까지 공백을 넣으십시오. 단일 람다식을 가진다면, 가능하다면 괄호 밖으로 빼는 것이 좋습니다.

 

 

람다에 레이블을 지정한다면, 레이블과 중괄호 시작 사이에 공백을 넣지 마십시오.

 

 

여러줄의 람다에서 파라미터의 이름을 선언할 때, 이름과 화살표를 첫번째 줄에 두고 새로운 줄을 입력하십시오.

 

 

파라미터의 리스트가 너무 길다면 화살표를 분리된 줄에 두십시오.

 

 

- Trailing commas

trailing comma는 여러 요소 중 마지막 항목 뒤의 쉼표입니다.

 

 

Trailing comma의 사용은 여러 이점이 있습니다.

• 변경된 값에 포커스가 집중되므로 버전 관리에서의 차이가 깔끔해집니다.
• 요소를 추가하거나 재정렬하는 것이 쉬워집니다 – 요소를 변경할 때 쉼표를 추가하거나 삭제할 필요가 없습니다.
• 객체 초기화 같은 코드의 생성을 간단하게 해줍니다.

Trailing comma는 전적으로 선택사항입니다 – 없이도 코드는 동작합니다. Kotlin 스타일 가이드는 선언부에서 trailing comma를 사용하는 것을 권장하며 호출부의 재량에 맡깁니다.

 

IntelliJ IDEA formatter에서 trailing comma를 활성화하려면, Settings/Preferences | Editor | Code Style | Kotlin으로 이동하여 Other 탭을 열고 Use trailing comma 옵션을 선택하십시오.

 

---

Documentation comments

내용이 긴 문서 주석의 경우에는, 별도의 줄에 /**로 시작하며 후속 줄은 별표로 시작합니다.

 

 

짧은 내용은 한 줄에 입력할 수 있습니다.

 

 

일반적으로 @param과 @return 태그를 사용하는 것을 피하십시오. 대신, 매개변수의 설명과 반환 값을 문서 주석에 통합하고 매개변수가 언급되는 곳에 링크를 추가합니다. 긴 설명이 필요하여 본문의 흐름에 맞지 않는 경우에만 @param과 @return을 사용하십시오.

 

 

---

Avoice redundant constructs

일반적으로 코틀린의 특정 구문이 선택사항이며 IDE에서 중복으로 강조된다면 코드에서 생략해야합니다. 단지 "명확성"을 위해서 불필요한 요소를 남겨두지 마십시오.

 

- Unit return type

함수가 Unit을 반환한다면, 반환 타입은 생략되어야 합니다.

 

 

- Semicolons

가능한 모든 세미콜론은 생략하십시오.

 

- String templates

문자열 템플릿에 간단한 변수를 삽입하는 경우 중괄호를 사용하지 마십시오. 중괄호는 더 긴 표현식에만 사용해야합니다.

 

 

---

Idiomatic use of language features

- Immutability

가변보다 불변 데이터를 더 사용하십시오. 지역변수와 프로퍼티가 초기화 이후에 변경되지 않는다면 var보다 val로 선언하십시오.

 

변경되지 않는 컬렉션을 선언하기 위해 항상 불변 컬렉션 인터페이스 (Collection, List, Set, Map)을 사용하십시오. 컬렉션 인스턴스를 생성하기 위해 팩토리 함수를 사용한다면 가능한 불변 컬렉션 타입을 반환하는 함수를 사용하십시오.

 

 

- Default parameters values

오버로드 된 함수를 선언하는 것보다 기본 파라미터 값이 있는 함수를 사용하십시오.

 

 

- Type aliases

코드베이스에서 사용되는 타입 파라미터의 함수 타입이나, 타입이 여러번 사용되는 경우 type alias를 정의하는 것이 좋습니다.

 

 

이름 충돌을 피하기 위해 private or internal type alias를 사용하는 경우 Packages and Imports↗에 나온 import … as …를 사용하십시오.

 

- Lambda parameters

람다가 짧고 중첩되지 않는다면 파라미터를 명시적으로 나타내는 것보다 it 규칙을 사용하는 것이 권장됩니다. 파라미터를 가진 중첩된 람다라면 항상 파라미터를 명시적으로 선언해 주어야 합니다.

 

- Returns in a lambda

람다에서 여러개의 레이블된 반환을 피하십시오. 하나의 끝을 갖도록 람다를 재구성하는 것을 고려하십시오. 가능하지 않거나 명확하지 않다면, 람다를 익명 함수로 변경하는 것이 좋습니다.

 

람다의 마지막 문장에서 레이블된 반환을 사용하지 마십시오.

 

- Names arguments

메소드가 동일한 유형의 여러 매개변수를 사용하거나 Boolean 타입을 갖는경우, 모든 매개변수의 의미가 명확하지 않은 경우 named argument를 사용하십시오.

 

 

- Conditional statements

try, if, 그리고 when의 표현법을 사용하십시오.

 

 

 

 

위는 다음과 같은 경우에 좋습니다.

 

 

 

 

- if versus when

두개의 조건에서는 when보다는 if를 사용하십시오.

if를 사용했을 경우

 

 

when을 사용했을 경우

 

 

when은 세개 이상의 옵션에서만 사용하길 권장합니다.

 

- Nullable Boolean values in conditions

조건문에서 nullable Boolean을 사용해야 한다면, if (value == true) 혹은 if (value == false)를 사용하여 확인하십시오.

 

- Loops

반복을 위해선 고차 함수 (filter, map 등) 을 사용하는 것이 좋습니다. 예외 : forEach의 수신자가 nullable 이거나 더 긴 호출 체인의 일부로 사용되지 않는다면 일반적인 for루프를 사용하는 것이 좋습니다.

 

복잡한 표현식에서 여러 고차함수나 반복을 선택할 때, 각 케이스의 작업 비용이나 성능면에 대해서 항상 고려해야합니다.

 

- Loops on ranges

until 함수를 사용하여 개방 범위를 반복하십시오.

 

 

- Strings

문자열 연결보다는 문자열 템플릿을 사용하십시오.

\n 이스케이프 시퀀스를 사용하는 것보다 여러 줄의 문자열을 사용하십시오.

 

여러 줄의 문자열에서 들여쓰기를 유지하기 위해서, 내부 들여쓰기가 필요하지 않은 경우에는 trimIndent를, 필요한 경우에는 trimMargin을 사용하십시오.

 

 

Java and Kotlin multiline strings↗

 

- Functions vs properties

매개변수가 없는 함수는 read-only 프로퍼티로 대체될 수 있습니다. 의미는 비슷하지만 서로 선호하는 스타일 규칙이 있습니다.

 

다음과 같은 경우 함수보다 프로퍼티로 적합합니다.

• throw 하지 않을 경우
• 계산 비용이 저렴할 때 (첫번째 실행에 캐시될 때)
• 오브젝트의 상태가 변경되지 않았을 경우 호출에 대해 동일한 결과를 받을 때

 

- Extension functions

확장 함수를 자유롭게 사용하십시오. 주로 오브젝트를 대상으로 하는 함수가 있다면 해당 오브젝트를 수신자로 하는 확장 함수를 만드는 것이 좋습니다. API 오염을 최소화 하기 위해서, 확장 함수의 가시성을 상황에 따라 제한하십시오. 필요하다면 지역, 멤버, 혹은 private visibility를 가진 최상위 확장 함수를 사용하십시오.

 

- Infix functions

두 오브젝트가 비슷한 역할을 하는 경우만 infix로 함수를 선언하십시오.
Good examples: and, to, zip.
Bad example: add.

 

수신 객체를 변경하는 경우에는 infix로 메소드를 선언하지 마십시오.

 

- Factory functions

클래스에서 팩토리 함수를 선언할 때, 클래스 이름과 같은 이름을 피하십시오. 팩토리 함수의 특징을 살리기 위해 명확한 이름을 사용하십시오. 정말 특별한 의미가 없을 때에만 클래스 이름과 동일하게 사용하십시오.

 

 

오브젝트가 다른 슈퍼클래스의 생성자를 호출하지 않고 기본값을 가지고 하나의 생성자로 줄일 수 없는 여러개의 오버로드 생성자를 가지고 있다면 오버로드 생성자들을 팩토리 함수로 대체하는 것이 좋습니다.

 

- Platform types

플랫폼 유형의 표현식을 반환하는 public 함수는 명시적으로 코틀린 타입을 선언해야합니다.

 

 

플랫폼 유형의 표현식으로 초기화 된 모든 프로퍼티(패키지 레벨, 클래스 레벨)는 명시적으로 코틀린 타입을 선언해야합니다.

 

 

플랫폼 타입의 표현식으로 초기화된 지역 변수는 타입을 명시하지 않아도 상관 없습니다.

 

 

- Scope functions apply/with/run/also/let

코틀린은 주어진 객체의 context에서 코드블럭을 실행하는 함수를 제공합니다.:let, run, with, apply, also. 상황에 맞는 scope function을 선택하기 위해서 Scope Functions↗를 참조하십시오.

 

---

Coding conventions for libraries

라이브러리를 작성할 때, API 안정성을 위해 다음 추가 규칙을 따르는 것이 좋습니다.

• 항상 멤버의 접근 제한자를 명시합니다. (실수로 public API에 선언을 노출하지 마십시오.)
• 함수의 반환 타입과 프로퍼티 타입을 명시적으로 지정하십시오. (구현이 변경될 때 실수로 반환형을 바꾸는 것을 방지합니다.)
• 새로운 문서를 필요로 하지 않는 overrides를 제외한 모든 public 멤버에 대해서 KDoc을 제공하십시오. (라이브러리 문서의 생성을 지원합니다.)

---

https://kotlinlang.org/docs/coding-conventions.html 

Coding conventions | Kotlin