3화.개발업무와 관련된 문화 코딩 규칙 정하기 - 숏폼플레이(유튜브쇼츠, 무료 동영상)

코딩 규칙 정하기

개발 업무에서 규칙을 정하는 것이 얼마나 중요한지는 모두가 알고 있을 것이다.

혼자 개발하는 프로젝트라면 크게 중요하지 않다고 생각할 수 있지만, 인원이 1명 이상인 순간부터 상황이 달라진다. 같은 리포지토리에 여러 명이 동시에 작업하게 되면 서로 다른 개발 스타일과 관점이 충돌할 수밖에 없기 때문이다. 따라서 최소한의 코딩 규칙을 정해두고 지키는 것이 좋은 개발 문화를 만드는 시작이라고 생각한다.

코딩 규칙을 정하면 좋은 이유

• 코드의 커뮤니케이션이 쉬워진다.

• 신규 입사자나 외부 협업자가 들어와도 빠르게 적응 가능하다.

• 코드 리뷰 시 규칙 기반으로 논의가 가능하다.

• 코드 품질이 자연스럽게 높아지고, 가독성이 개선된다.

• 정적 분석 도구(예: Ktlint)와 연계하여 코드 품질을 강제할 수 있다.

나의 경우 Kotlin, Java 기반으로 개발을 주로 해왔으며, 최근에는 AI 관련 개발을 진행하고 있다.

특히 Kotlin을 사용할 경우, 기본적인 코딩 규칙을 정리하고 상황에 맞게 추가 규칙을 정의하는 것이 효과적이라고 생각한다.

예를 들어 다음과 같은 코드가 있을 수 있다.

isEmpty:Boolean = false
//아래 2가지는 동일하게 동작하는데 sonarqube 에서는 첫번째는 통과 아래는 실패로 나온다. 
//개인적으로는 두번째가 가독성 측면에서는 좋다고 보지만 상황에 따라서 규칙을 정하면 된다.
if(!isEmpty) 
if(isEmpty == false)

위 두 코드는 같은 동작을 하지만 SonarQube 기준에서는 첫 번째가 통과되고 두 번째는 실패하는 경우가 있다. 가독성 관점에서는 두 번째가 명확하다고 보지만, 팀의 상황과 도구 기준에 따라 규칙을 통일해야 한다

Kotlin 코딩 규칙 주요 포인트

• Kotlin 기본 스타일 가이드를 따른다.

• 변수명, 클래스명에는 언더스코어(_) 사용을 지양한다.

• 주석은 KDoc을 활용하여 읽기 쉬운 문서를 작성한다.

• Klint, GitHub Action 같은 자동화 도구를 활용하여 소스 Push 시점에서 Fail 체크를 하도록 한다.

• 클래스나 인터페이스는 Companion Object를 제외하고 문서 설명을 반드시 포함한다.

• if/when 문, while/for 루프는 일관성 있는 포맷을 유지한다.

• 클래스 내 멤버의 순서는 읽기 전용 → 읽기/쓰기 → 초기화 → 생성자 → 함수 순으로 정리한다.

• 상수 값은 SNAKE_CASE로 선언하고, const 수식자를 사용한다.

// GOOD
private val modifiableElementList: MutableList = mutableListOf()
val elementList: List = modifiableElementList
// BAD
private val _elementList: MutableList = mutableListOf()
val elementList: List = _elementList

코멘트

KDOC이나 Dokka 규칙을 따른다.

또한 Klint와 github Action 같은 자동화를 한다면  소스 push 시점에서 Fail 체크가 가능하기 때문에  용이하다.

나 같은 경우는 klint를 주로 사용하는데 룰을 정의하고 push 전체 한번 체크 후 Push를 진행했던 것 같다.

클래스

각 클래스, 인터페이스 또는 오브젝트는 companion object 및 익명 오브젝트를 제외하고 문서 설명을 포함해야 한다.

문서에는 다음과 같은 두 가지 요구사항이 있다.

• Javadoc/Kdoc 규칙을 따르자. 예를 들어, 코멘트 스타일은 "이어야 한다./**... */
• 먼저 "유형이 무엇인지 , 유형이 무엇인지"를 설명하는 짧은 요약으로 명사 구절을 시작하자.
• 그다음, 선택적 문장은 사용법, 제한사항 등을 설명하기 위해 짧은 요약에 따를 수 있다.

참고: 설명서가 없는 기존 클래스를 찾으면 코멘트를 작성하자.

제어 흐름

"if"/"when" 표현/표현

• if-message:호출자가 결과를 소비한다(예: 할당, 반환 값 또는 함수 매개 변수).
  •  if-expression의 본문은 동일한 코드 라인에 모두 적합한 경우 단일 라인 형식(*)으로 갈 수 있으며, 그렇지 않은 경우 두 가지 줄의 본체에 대해 다중 라인 형식(**)을 적용해야 한다.
• if-datement:if-statement 본문은 다중 행 형식과 일치해야 한다.
• (*) 단일 줄 형식:컬브 브레이스({})를 사용하면 안 된다.
• (**) 다중 행 형식:({})가 필요하다.

다음 예제를 참조해 보자.

// Standard style
if (condition) {
    statement()
}
// with else
if (condition) {
    statement()
} else {
    anotherStatement()
}
// Assignment on a line
val value = if (condition) valueA else valueB
 
val longLongLongLongLongNameValue = if (condition) valueA else valueB
  
// Assignment with block
val anotherValue = if (condition) {
    longLongLongLongLongLongNameValueA
} else {
    longLongLongLongLongLongNameValueB
}
  
val oneMoreValue =
    if (longLongLongCondition) {
        longLongLongLongLongLongNameValueA
    } else {
        longLongLongLongLongLongNameValueB
    }

할당 또는 반환 값에 식을 사용할 경우 각 본문 블록에는 식이 하나만 있어야 한다

예를 들어, 다음 코드는 지양한다.

// BAD: 각 본문 블록에는 추가 명령문이 있습니다. 본문을 함수로 추출하여 "if" 표현식 값을 사용합니다.
val string = if (i % 2 == 0) {
    methodCall()
    anotherMethodCall()
    "even"
} else {
    furtherMoreMethodCall()
    "odd"
}

• 식이 할당 또는 반환 값의 다른 목적으로 사용되어서는 안 될 경우 값이다.

예를 들어, 다음 코드는 지양한다.

// BAD: "if" 표현식의 어떤 값도 메서드 인수로 사용할 수 없습니다. 먼저 로컬 값으로 정의하세요.
function(if (i % 2 == 0) "even" else "odd")
 
// BAD: 
"if" 표현식의 어떤 값도 함수 수신자로 사용할 수 없습니다. 먼저 로컬 값으로 정의하세요.
if (i % 2 == 0) {
    "even"
} else {
    "odd"
}.capitalize()

• 다중 조건 블록의 경우 인수가 없는 식을 사용해야 한다. 그렇지 않으면 가독성이 개선된 특수한 상황에서만 문을 사용해야 한다.

예제

// BAD
if (expression1) {
    doStuff()
} else if (expression2) {
    doOtherStuff()
} else {
    doOtherOtherStuff()
}
  
// GOOD
when {
    expression1 -> doStuff()
    expression2 -> doOtherStuff()
    else -> doOtherOtherStuff()
}

"while"/"for" 루프

마치 표현과 같이, 반면/대용 루프는 각 body 블록에 대해 브레이스를 가지고 있어야 하며 블록은 새로운 선으로 시작해야 한다.

(조건) 루프가 있는 동안 {}에 do을(를) 사용하지 말자.

빈 블록

빈 블록을 정의하려면 첫 번째 줄에 열린  브레이스를, 두 번째 줄에 닫힌 브레이스를 놓자.

https://android.github.io/kotlin-guides/style.html#empty-blocks).

try {
      doSomething()
  } catch (e: Exception) { // break the line for an empty block
  }
:

멤버 변수 순서

클래스, enum, interface, object 등의 멤버 오더는 안드로이드 스튜디오에서 제공하는 자바의 오더 포맷터를 따른다.

코틀린 주문 포맷터나 공식 컨벤션 등이 없기 때문에 자바코드가 코틀린으로 전환되면서 일관성을 제공하는 데 도움이 될 것이다.

그러나 "정적 필드"는 동반 대상의 필드에 의해 실현되기 때문에 최종적으로 배치되어야 한다.

순서는 다음과 같다.

• 읽기 전용 속성(val)으로 정의
• 읽기-쓰기 속성(var)으로 정의
• 초기화 블록(초기)
• 보조 생성자(구성자)
• 함수()
• 읽기 전용 속성 확장(val T.x)
• 읽기-쓰기 속성 확장(var T.x)
• 함수  extention(T.foo())
• 중첩 또는 내부 클래스, 열거형, 인터페이스 및 개체
• companion object 

다음 예제를 참조하자.

class Klass(val parameter: Value) {
 
    // Read-only properties
    val publicValue: Value = Value()
    private val value: Value = Value()
 
    // Read-write properties
    var publicVariable: Value = Value()
    private var variable: Value = Value()
 
    // Initialization block
    init {
        // ...
    }
 
    // Other constructors
    constructor(firstValue: Int, secondValue: Int) : this(Value())
 
    // Functions
    fun publicFunction() { ... }
 
    private fun privateFunction() { ... }
 
    // Extensions of read-only properties
    val  T.publicReadonly: Value get() = Value()
    private val  T.readonly: Value get() = Value()
  
    // Extensions of read-write properties
    var  T.publicReadWrite: Value
        get()
        set()
    private var  T.readWrite: Value
        get()
        set()
  
    // Extensions of functions
    fun  T.publicFunction() { ... }
  
    private fun .privateFunction() { ... }
    // Nested or inner classes, enums, interfaces, and objects
    enum class EnumType private constructor(val enumField: Int) {
        DEFAULT(1),
        A_ENUM_TYPE(2),
    }
 
    private data class NestedDataClass(val int: Int)
 
    // Constants
    companion object {
        const val PRIMITIVE_CONSTANT = 0
 
        @JvmField
        val NON_PRIMITIVE_CONSTANT: OtherClass = OtherClass()
    }
}

각 범주에 대해 가능한 한 다음과 같은 규칙을 지키도록 권장한다.

• public 이  private 보다  member ordering 이 높다.
• 정적 항목이 동적으로 결정된 항목 이상임
• 추상화 수준이 높은 항목은 낮은 추상화 수준 항목보다 높다.

유형 선언

• 형식 선언은 반드시 지켜야 한다.
  • 생성자 또는 메서드의 매개 변수
  • 비유닛 리턴형 함수
  • 전부 **var** properties
• 다음 형식 선언을 삭제하십시오.
  • 단위반환형법
  • "const" 한정자가 있는 모든 필드
• ... 에 대한 형식 선언을 유지하거나 취소할 수 있다.
  • 로컬 값 및 변수
  • 람다의 파라미터 유형
  • val
  • 가시성과 관계없이 생성자에 대한 호출을 사용하여 즉시 할당되는 속성

다음 예제를 참조하자.

// You must keep type for public values and any variables
private var variable: Type = Type() // Type required because `var`
 
// You must keep type if the right value is not direct constructor call or primitive value
private val array: Array = arrayOf(1, 2, 3) // `arrayOf` is not a constructor.
private val sum: Int = 1 + 2 // The right value is the result of `plus` function.
private val valueWithApply: Type = Type().apply { ... } // `.apply` is appended.
 
// You may keep or drop the type for values instantiated with constructor calls
// With constructor call
val value: Type = Type() // Kept (somewhat repetitive)
val value = Type() // Dropped
private val value1: Type = Type() // Kept (somewhat repetitive)
private val value2 = Type( // Dropped
    parameter,
    parameter2
)
// With primitive value assignment
private val value3: Int = 1 // Kept
private val value4 = 1 // Dropped
 
// Anti-pattern: dropping type declarations in situations other than explicit constructor calls
private val value = Type.generateInstance() // Not an actual constructor call
private val value2 = Type( // Starts with a constructor call...
    parameter,
    parameter2
).toOtherType() // But may be deceptive
 
// You must keep the type for private variables
private var variable: Superclass = Subclass() // The type may be different than the initial value, because it can be reassigned
/* ... */
        variable = OtherSubclass() // The variable might take on another type
    } else {
        variable = Superclass() // ...or it might be assigned with the super-type
// Even if the type was dropped, this code would be compiled successfully due to Kotlin's inferred typing system, but this isn't immediately obvious to readers
 
// You must keep return type with non-Unit methods
fun nonUnitFunction(): Int = 1
 
// You must skip return type if it is Unit
fun unitFunction() = Unit
 
// You must keep parameter type
fun unitFunction(i: Int) {
    // You may skip local value/variable type...
    val j = 0
    // or you may also keep the type.
    val k: Int = i + j
 
    // For lambdas, you can choose from any valid format.
    val firstLambda: (Int) -> Int = { it + 1 }
    val secondLambda = { i: Int -> i + 1 }
    val thirdLambda: (someMeaningfulName: Int) -> Int = { anotherName -> anotherName + 1 }
}

함수 정의

헤더 포맷

헤더 형식은 Kotlin 코딩 규칙의 클래스 헤더 형식에 따른다. 헤더가 충분히 짧으면 반드시 한 줄에 써야 한다. 헤더가 긴 경우 각 매개변수 선언은 별도의 줄에 있어야 한다. 다음 예제를 참조하십시오.

fun shortHeader(): Int {
    // ...
    // ...
}
  
fun shortHeader(parameter: Int): Int {
    // ...
    // ...
}
  
fun longHeader(
        parameter: Parameter,
        anotherParameter: Parameter,
        oneMoreParameter: Parameter
): Type {
    // ...
    // ...
}
 
fun longHeaderWithUnitReturnType(
        parameter: Parameter
) {
    // ...
    // ...
}

Brace 및 = 정의 기호

• 하나의 표현식으로 함수를 정의하려면 반환 유형이 단위인 경우에도 ****= 기호를 사용하자.
• 여기에는 if, when, function calls with lambda와 같은 표현이 포함된다.
• 사용하다= Unit이 규칙의 예외는 보조 생성자가 다른 생성자에게 위임하는 경우다.
• 빈 함수를 정의하십시오.

다음 예제를 참조하자.

fun function(): Int = 1 + 2
  
fun function(parameter: Int): Int =
    1 + parameter
 
fun anotherFunction(): Type = Type().also {
    it.variable = "variable"
    it.anotherVariable = "variable"
}
  
fun whenFunction(type: Type): String = when(type) {
    Type1 -> "Type1"
    Type2 -> "Type2"
}
 
fun unitFunction() = anotherUnitFunction()
  
fun emptyFunction() = Unit
  
// Exception for secondary constructors
constructor(type: Type) : super(type)
constructor(type: Type, anotherType: Type) : this(type)

상수 값

상수 값은 자본화됨_으로 선언해야 함스네이크_케이스_라이크_이것. 또한 동반 객체의 필드 또는 글로벌 값으로 정의해야 한다(다음 섹션 참조). 상수 값이 원시 값이나 문자열인 경우 const 수식어를 추가해야 한다. 기본 상수가 아닌 상수의 경우, Java에서 표시되도록 하려면 @JvmField 주석을 추가해야 한다.

const val PRIMITIVE_CONSTANT = 0
 
@JvmField
val NON_PRIMITIVE_CONSTANT: NonPrimitive = NonPrimitive()

global value  및 global function

글로벌 값, 객체(순수함수가 아닌 경우도 있음) 또는 확장자를 변경하지 않고 기능 또는 전역 값을 정의하려면 다음과 같이 적절한 패키지에 새 파일을 생성하십시오.

YourConstants.kt

**`package`** `com.linecorp.yourpackage`

`const **val**` `YOUR**_**CONSTANT**:**` `Int **=**` `0;`

**`@**JvmField`

**`val`** `YOUR**_**ANOTHER**_**CONSTANT**:**` `Value **=**` `Value();`

YourUtils.kt

**`package`** `com.linecorp.yourpackage`

`fun yourUtilityFunction()**:**` `ReturnValue {`

`// ...`

`**return**` `ReturnValue()`

`}`

Java에서 접속할 때 파일 이름 또한 클래스 이름으로 사용되기 때문에 파일 이름은 다음과 같이 제한된다.

• 파일 이름 접미사는 상수의 "Constants"여야 한다.
• 효용 함수의 파일 이름 접미사는 "Utils"여야 한다.
• 확장 기능 모음에 대한 파일 이름 접미사는 "확장"이어야 한다.

글로벌 확장을 만들려면, 다음 소유자에게 요청하는 것이 좋다.

Lamda

중첩된 람다(람다(람다))를 피하십시오.

중첩된 람다는 종종 읽을 수 없다. 게다가, 그것은 전형적인 코드 냄새의 신호다. 대신 메서드 참조, 메서드 접속사, 플랫맵 또는 기타 메서드를 사용하자. 예를 들어 다음과 같은 코드는 금지된다.

//BAD
list.map { innerList ->
    innerList.map {
        // DON'T DO THIS !!!
    }
}

예외:

예외적으로 외부 람다가 글로벌 범위 또는 클래스의 최상위 수준(=연산자 포함 함수/값 할당 범위 포함) 바로 아래에 있으면 중첩된 람다를 사용할 수 있다. 허용 가능한 코드는 다음과 같다.

class Klass {
 
    val intValue: Int by lazy {
        intList.sumBy { it + it * it }
    }
 
    fun function(mutableObject: MutableClass?, list: List) = mutableObject?.apply {
        firstEven = list.first { it % 2 == 0 }
        firstOdd = list.first { it % 2 != 0 }
        // And more
    }
}

다음 코드는 허용되지 않는다.

//BAD
class Klass {
 
    fun function(mutableObject: MutableClass?, list: List) {
        mutableObject?.apply {
            firstEven = list.first { it % 2 == 0 }
            firstOdd = list.first { it % 2 != 0 }
        }
        // And more
}

긴 람다 피한다.

읽기 쉽도록 "긴" 람다는 피해야 한다. 다음 조건 중 하나를 만족하는 람다는 "긴" 람다.

• 반환 식을 제외한 2개 이상의 문장이 있는 람다.
• if 식, a when 식 또는 for/while 루프가 있는 람다.

다음 예를 참조하자.

// Short lambda expression: 1 statement and 1 return expression
list.map {
    methodCall(it)
    returnValue(it)
}
 
// Long lambda: with for when
dialogBuilder.setPositiveButton("OK") { dialog: DialogInterface, which: Int ->
    when (which) {
        0 -> // ...
        else -> // ...
    }
}
  
// Long lambda: 2 statements (the second line is not return expression)
obj.apply {
    methodCall()
    anotherMethodCall()
}

"긴" 람다를 사용하지 않으려면 표현식을 방법으로 추출하고 메서드 참조를 사용하여 가능하면 명명된 클래스를 만드십시오.

예외:

편의상 "긴" 람다(long)는 다음과 같은 경우에 허용된다.

• 반환 값으로 직접 사용되는 람다
• 함수의 마지막 인수로 직접 사용되는 람다. 여기서...
• 다른 주장은 람다가 아니다.
• 람다는 위임 또는 수정 수신기를 포함한 기능의 반환 값을 생성하는 데만 사용된다.
• 함수 반환 값은 호출자의 할당 또는 반환 값에 사용되지 않거나 직접 사용된다.

// OK: Long lambda directly used for return value
fun createComparator(): (Int, Int) -> Int = { x: Int, y: Int ->
    // Code...
    // Code...
    result
}
 
// OK: Long lambda used for assignment directly.
val mappedList = list.map {
    when (it) {
        0 -> it
        else -> it + 1
    }
}
  
// OK: Long lambda used for delegation directly.
val view by lazy {
    // initialization
    // another initialization
    inflatedView
}

다음 코드는 허용되지 않음:

// BAD: the result of function taking lambda is not directly used for assignment
val mappedList = list.map {
    when (it) {
        0 -> it
        else -> it + 1
    }
}
.map { /* another map */ }
  
// BAD: the result of function taking lambda is not directly used for assignment
val value: View = parent?.let {
    // initialization
    // another initialization
    foundView
} ?: defaultView

로컬 값/변수와 관련하여 닫기를 반환하지 않음

대신 concrete 클래스 또는 객체를 만드십시오.

try-catch 블록별로 예상된 예외 유형을 명시적으로 지정하십시오.

공식 가이드 외에도 각 조직 상황에 맞게 추가 규칙을 논의하고 정의하는 것이 중요하다. 그리고 규칙은 문서로만 존재하는 것이 아니라 자동화 도구와 연계하여 실질적인 코드 품질 향상을 이끌어내야 한다.

실전에서 느낀 점

개발 문화를 잡아가는 과정에서 기본 규칙 + 팀과의 합의 + 자동화 및 정적 분석 도구의 삼박자가 가장 이상적이라고 생각한다. 그래야만 코드가 양산될 때 가독성 높은, 읽기 쉬운 코드가 될 확률이 높다.

내가 여러 국가 개발자들과 협업하면서 가장 크게 느낀 점은, 사람마다, 인종마다 코딩 스타일이 천차만별이라는 것이다. 특히 한국, 인도, 기타 국가들의 개발자들이 작성한 코드는 각각 또 다른 매력이 있다. 다양한 코드를 보면서 나만의 스타일을 찾아가는 것도 좋은 방법이라 생각한다.

AI 시대에 접어든 지금, 자신이 작성한 코드를 ChatGPT 같은 AI의 도움으로 개선하는 것도 좋은 습관이다. 물론 모든 것을 AI에 의존하는 것은 좋은 태도가 아니지만, AI가 제공하는 대안을 참고하면서 더 나은 코드를 만들어내는 개발자가 되어야 한다고 생각한다.

---

마치며

이번 편에서는 코딩 규칙을 정하는 이유와 실전 적용 방법을 소개했다.

작지만 명확한 규칙 하나가 팀의 커뮤니케이션과 생산성에 큰 차이를 만들어낸다.

다음 편에서는 코드 리뷰 문화와 그 원칙을 정리하여, 코드 품질과 팀 협업을 한층 더 강화하는 방법을 소개하고자 한다.

---

다음 편 예고

개발 문화 정립 시리즈 - 4화 : 코드 리뷰 원칙과 문화 정립하기

좋은 코드 리뷰는 팀의 성장 엔진이다.

다음 편에서는 코드 리뷰 시 지켜야 할 원칙과, 리뷰 문화를 건강하게 만들기 위한 팁을 공유할 예정이다.