2025-12-15
1일 1아티클
LY
주석 작성법
문제 상황
/**
* 주어진 [englishText]를 마침표(`'.'`)로 분할하고, 분할된 문자열에서 빈 문자열(`""`)을 제거합니다.
* 그 다음 각 분할된 문자열을 다시 공백(`' '`) 또는 쉼표(`','`)로 분할한 후 빈 리스트를 제거합니다.
* 마지막으로 그 결과(문자열의 중첩 리스트)를 반환값으로 반환합니다.
*/
fun ...(englishText: String): List<List<String>> {
val sentences = englishText
.split(SENTENCE_SEPARATOR)
.asSequence()
val wordsInSentences = sentences
.map { it.split(WORD_SEPARATOR_REGEX).filter(String::isNotEmpty) }
return wordsInSentences
.filter(List<String>::isNotEmpty)
.toList()
}
...
private val SENTENCE_SEPARATOR: String = "."
private val WORD_SEPARATOR_REGEX: Regex = """[ ,]+""".toRegex()
문서화 주석 작성 방식
- 첫 문장만 읽어도 개요를 이해할 수 있도록 작성 필요
- 가장 중요한 요소 선택
- 코드보다 높은 추상화 수준의 설명
개선 결과
/**
* 영어 문자열 [englishText]를 문장 단위로 분할하고, 다시 단어 단위로 분할해서 얻은 리스트의 리스트를 반환합니다.
*
* 여기서 '문장'은 마침표(`'.'`)로 구분된 부분 문자열을 의미하고,
* '단어'는 공백(`' '`) 또는 쉼표(`','`)로 구분된 부분 문자열을 의미합니다.
* 또한 빈 문장이나 빈 단어는 반환값에서 제외됩니다.
* 예를 들어 `" a bc. .d,,."`가 주어지면 `[["a", "bc"], ["d"]]`를 반환합니다.
*/
인라인 주석 작성 방식
-
무엇을 먼저 설명할지가 중요
-
예. ‘무엇을 하는지’를 처음 작성했으나, 임시방편 코드에서는 별로 중요치 않은 내용임. 존재 이유를 먼저 쓰는 것이 훨씬 중요! ```kotlin
val someValue = device.someValue device.someFunction() …
// 아래는 잘못된 주석 작성 예 // ==================== // 강제적으로
someValue를 이전 값으로 리셋합니다. // 기기 X에서는someFunction이 호출되면someValue의 값을 변경하는데 // 이 동작은 foo API의 사양을 위반하기 때문입니다. device.someValue = someValue// 아래는 개선된 주석 작성 예 // ====================
// 이 코드는 기기 X 고유의 버그를 회피하기 위한 것입니다. // 기기 X는someFunction내에서someValue를 변경하지만 이는 foo API의 사양을 위반합니다. device.someValue = someValue
**TODO 주석 작성 방식**
- 예. '앞으로 어떻게 하고 싶은지', '어떤 상태가 이상적인지'가 중요하므로 먼저 작성!
```kotlin
// 아래는 잘못된 주석 작성 예
// ====================
// TODO: `var abc`와 `var xyz`는 모두 `fun foo`에 할당되므로
// `foo`를 리팩토링하기 전까지는 변경하기 어렵다.
// 본래 `abc`는 `xyz`에서 계산하여 구할 수 있으므로 삭제할 수 있다.
var abc :...
var xyz :...
// 아래는 개선된 주석 작성 예
// ====================
// TODO: `var abc`의 값을 `var xyz`에서 구하도록 하고 `abc`를 삭제한다.
// 다만 이를 위해서는 먼저 `fun foo`를 리팩토링해야 한다.
// (`foo`가 `abc`와 `xyz`에 할당하기 때문이다)
var abc :...
var xyz :...
주석 작성 시, 무엇을 먼저 설명할지 신중하게 선택할 것
오늘 배운 것
- 잡페어
내일 할 일
- 잡페어(con.)