[좋은 코드, 나쁜 코드] 다른 개발자와 코드 계약

자신의 코드와 다른 개발자의 코드

다른 개발자들이 활발하게 코드를 변경하더라도 코드의 품질이 유지되려면 코드가 튼튼하고 사용하기 쉬워야 한다. 고품질 코드를 작성할 때 가장 중요한 고려 사항 중 하나는 다른 개발자가 변경하거나 코드와 상호작용할 때 발생할 수 있는 문제는 없는지, 또 발생한다면 그 문제를 어떻게 완화할 수 있을지를 이해하고 선제적으로 조치하는 것이다. 우리는 혼자 일하지 않는 이상 다른 개발자들을 고려하지 않고는 고품질의 코드를 작성할 수 없다.

코드를 작성할 때 다음 세 가지를 고려하는 것이 유용하다.

• 자신에게 명백하다고 해서 다른 사람에게도 명백한 것은 아니다.
• 다른 개발자는 무의식중에 내 코드를 망가뜨릴 수 있다.
• 시간이 지남에 따라 자신의 코드를 기억하지 못한다.

자신에게 분명하다고 해서 다른 사람에게도 분명한 것은 아니다

어느 시점에 이르면 다른 개발자가 내가 작성한 코드와 상호작용하거나, 내 코드를 변경하거나, 내 코드가 의존하고 있는 코드를 변경해야 할 수도 있다는 것을 기억해야 한다. 그들은 그 문제를 이해하고 어떻게 해결할지에 대해 생각할 수 있는 시간을 아직 충분히 갖지 못한 상태다. 내가 코드를 작성할 당시에는 너무도 분명해 보였던 것들이 그들에게는 분명하지 않을 것이다.
단순히 주석문을 많이 작성해야 한다는 의미가 아니다. 코드를 이해하기 쉽고 코드 자체로 설명이 되게 하는 것이 좋은 방법이다.

다른 개발자는 무의식중에 내 코드를 망가뜨릴 수 있다.

내가 작성한 코드는 나에게 가장 중요할지 모르지만, 회사의 다른 개발자들은 그것에 대해 잘 알지 못하기 때문에 그들이 내 코드를 접할 때 그 코드가 왜 존재하는지 혹은 무슨 일을 수행하는지에 대한 사전 지식을 가지고 있지 않을 수 있다. 때문에 다른 개발자가 의도치 않게 잘 실행되던 코드를 작동하지 않게 하거나 오용하는 방식으로 코드를 추가하거나 수정할 가능성이 크다.

시간이 지나면 자신의 코드를 기억하지 못한다.

자신에게는 분명한데 다른 사람에게는 분명하지 않을 수 있다는 것, 혹은 다른 사람들이 무의식중에 자신의 코드를 작동하지 않게 만드는 것과 관련해 살펴본 모든 내용이 어느 순간 그대로 자신에게 적용된다. 1~2년 전에 작성한 코드를 다시 들여다보는 일은 다른 사람이 작성한 코드를 보는 것과 크게 다르지 않다. 배경지식이 거의 없거나 전혀 없는 사람에게도 자신의 코드가 이해하기 쉬어야 하고, 잘 작동하던 코드에 버그에 발생하는 것이 어려워야 한다. 이렇게 하는 것은 다른 사람에게 호의를 베푸는 것이기도 하지만 미래의 자신에게도 유익한 일이다.

내가 작성한 코드의 사용법을 다른 사람들은 어떻게 아는가

다른 개발자가 내가 작성한 코드를 사용하거나 내 코드에 의존하는 코드를 수정할 때, 그들은 내 코드를 어떻게 사용하는지 그 코드가 무슨 일을 하는지 파악해야 한다.

구체적으로 그들은 아래와 같은 사항을 이해할 필요가 있다.

• 여러 가지 상황에서 어떤 함수를 호출해야 하는지
• 클래스가 무엇을 나타내는지 그리고 언제 사용되어야 하는지
• 어떤 값을 인수로 사용해야 하는지
• 코드가 수행하는 동작이 무엇인지
• 어떤 값을 반환하는지

내가 작성한 코드를 어떻게 사용해야 하는지 알아내기 위해 다른 개발자가 할 수 있는 일은 아래와 같다.

• 함수, 클래스, 열거형 등의 이름을 살펴본다.
• 함수와 생성자의 매개변수 유형 또는 반환값의 유형 같은 데이터 유형을 살펴본다.
• 함수/클래스 수준의 문서나 주석문을 읽어본다.
• 직접 와서 묻거나 채팅/이메일을 통해 문의한다.
• 내가 작성한 함수와 클래스의 자세한 구현 코드를 읽는다.

이름 확인

자신의 코드를 다른 개발자가 어떻게 사용해야 하는지에 대해 가장 잘 전달할 수 있는 방법 중 하나는 이름을 잘 짓는 것이다.

데이터 유형 확인

제대로만 한다면 데이터 유형을 확인하는 것 역시 다른 개발자로 하여금 자신의 코드를 올바르게 사용하도록 하기 위한 매우 신뢰할 만한 방법이다.

문서 읽기

코드를 사용하는 방법에 관한 문서는 두 가지 이상의 형태로 존재할 수 있으며 다음을 포함한다.

• 함수 및 클래스 수준의 비공식적인 주석문
• 자바독(JavaDoc)과 같은 좀 더 공식적인 코드 내 문서
• 외부 문서(README.md, 웹 페이지, 지침 문서 등)

이 모든 것이 매우 유용하지만, 다른 개발자가 코드를 올바르게 사용하도록 하기 위한 방법으로 어느 정도까지만 신뢰할 수 있다.

• 다른 개발자가 이 문서들을 읽을 것이라는 보장이 없으며 실제로 읽지 않을 때가 더 많다.
• 설령 읽더라도 잘못 해석할 수 있다. 다른 개발자들이 익숙하지 않은 용어를 사용할 수도 있고, 코드가 해결하려는 문제에 관해 다른 개발자 들이 가지고 있을 지식의 수준이나 정도에 대해 잘못된 가정을 바탕으로 문서를 작성할 수도 있다.
• 문서의 업데이트가 제대로 안 될 수 있다. 개발자가 코드를 변경할 때 마다 문서를 업데이트해야 하는데, 이것을 잊어버리면 코드에 대한 문서의 내용이 더 이상 유효하지 않게 된다.

직접 물어보기

팀으로 일하면 코드를 사용하는 방법에 대해 다른 개발자들이 질문해 오는 경우가 종종 있는데, 코드를 작성한지 얼마되지 않았다면 이 접근법이 상당히 효과적일 수 있다.

코드를 살펴보는 것

코드 사용 방법에 대한 가장 확실한 답을 얻을 수 잇는 방법은 코드의 자세한 구현 세부 사항을 살펴보는 것이다. 하지만 이 접근법은 실용적이지도 않고, 코드의 양이 많으면 효과를 얻기 힘들다. 다른 개발자가 내 코드를 사용하기로 한다면 그것은 아마도 그들이 의존하고 있는 수많은 코드들 중 하나일 것이다. 그들이 의존하는 모든 코드의 구현 세부 사항을 살펴봐야 한다면, 어떤 기능을 구현할 때마다 수천 줄의 코드를 읽어야 할 것이다.

추상화 계층을 만드는 데 있어 요점은 개발자가 한 번에 몇 가지 개념만 처리해야 하고, 그 문제가 어떻게 해결되었는지 정확히 알지 못하더라도 하위 문제에 대한 해결책을 사용할 수 있어야 한다는 것이다. 코드를 사용하는 방법을 알기 위해 개발자가 구현 세부 사항을 읽어야 한다면 이는 분명히 추상화 계층의 많은 이점을 부정하는 것이 된다.

요약

• 코드베이스는 계속 변하고 일반적으로 여러 개발자에 의해 변경된다.
• 다른 개발자가 어떻게 코드를 해석하고 오용할 수 있을지 생각해보고, 이러한 가능성을 최소화하거나 오용이 불가능하게 만드는 방식으로 코드를 작성하는 것이 유용하다.

Reference
톰 롱. 『좋은 코드, 나쁜 코드』. 제이펍, 2022.