주피터노트북을 벗어나보자

데이터 분석 공부를 시작하는 분들 중 90% 이상은 주피터 노트북을 활용하는 데에서 출발하셨을 것입니다. 주피터 노트북은 데이터 분석 결과를 빠르게 확인할 수 있고 있다는 점에서 아주 간편하고 입문자들에게는 진입장벽이 낮은 도구입니다. 하지만 주피터노트북 형태의 코드는 정리가 되어있지 않으면 코드가 뒤죽박죽 섞일 수 있고, 재사용이 힘들어 유지보수를 하거나 협업을 하는 관점에서는 활용도가 매우 떨어집니다.

이런 상황에서 기술적인 방법론이 아닌, 클린코드에 대한 감을 잡을 수 있도록 가이드 형식의 내용을 정리해보았습니다.

대상 독자

  • 주피터 노트북으로 코딩에 입문하고, 현재까지도 사용 중이신 분
  • 연구와 PoC만 해오시다, 실제 프로덕션 코드를 작성할 시점에 맞닥뜨리신 분
  • 여태 홀로 일해야 하는 상황이었다가, 이제 협업을 하셔야 하는 분

1. 프로덕션 코드란…?

프로덕트에 쓰이는 코드는 간단히 말해, 실제 제품에 쓰이는 코드를 말합니다. 따라서 프로덕션 코드는 아래와 같은 조건들을 갖춰야 합니다.

  • 클린 코드

    • 읽기 쉽고, 간결하며, 명확한 코드는 유지보수와 협업에 필수

  • 모듈의 형태를 띄는 코드

    • 일련의 코드가 논리적인 구조에 따라 함수와 클래스 등으로 구분되어진 형태

  • 모듈

    • 파일 형태(ex. .py 확장자의 파일)로 구분되어, 효율적으로 재사용할 수 있도록 잘 정리된 코드
    • import 하여 쓸 수 있음

2. 클린 코드 작성하기

2.1. 의미 있는 이름의 사용

  1. 변수명, 함수명 등은 작업을 묘사하고 타입을 명시합니다.
    • get, convert, 등 동사를 통해 작업을 묘사
    • 하지만 모든 디테일을 다 넣은 긴 이름은 결코 좋은 이름이 될 수는 없음
  2. 비슷한 성향을 가졌다면 일관성을 가진 이름을 부여
    • ex)
      • ages, age (x)
      • age_list, age (o)
  3. 축약어나 한글자 변수명은 지양하는 것이 좋습니다.

2.2. 적절한 공백의 사용

  1. 공백을 사용하여 코드의 영역을 구분시키면, 관리하기도 좋고, 가독성도 향상됩니다.
  2. 한 줄에 79자 정도로 코드를 제한 하는 것을 권장합니다.

2.3. 모듈러 코드 작성

모듈러 코드를 작성하는 이유는 같은 코드를 반복해서 작성하지 않고도 재사용하는 것이, 장기적으로 봤을 때 유지보수 관점에서 더 낫기 때문입니다.

모듈러 코드를 작성할 때 지키면 좋을 가이드를 몇가지 알아보도록 하겠습니다.

  1. 반복하지 말 것 (Don’t repeat yourself - DRY
  2. 객체(함수, 클래스, 모듈 등)의 갯수를 최소화. 불필요하게 많은 객체는 오히려 역효과가 있음.
  3. 하나의 함수는 한가지 작업만을 수행해야 함.
    • 함수가 하나 이상의 작업을 수행할 경우, 재사용이나 일반화를 하는데 제한적임.
    • 만약 함수 내에서 AND의 요소가 발견된다면, 쪼개서 작성할 것을 추천함.
  4. 재사용을 위해 변수명, arguemnt명은 되도록이면 가장 기본적인 의미를 담는 것이 좋습니다.
    • 간단한 변수명일 수록 가독성이 향상
    • 다양한 상황에서의 재사용이 쉬워짐
  5. 하나의 함수당 argument 사용을 3개까지 제한하는 것을 권장합니다. 만약 4개 이상 사용하게 된다면, 함수를 쪼개어 구성하는 방안을 생각해보세요.

3. 리팩토링(Refactor)

리팩토링이란 코드의 기능에 영향을 끼치지 않은 상태를 유지하며 코드의 구조와 호율성을 향상시키는 작업입니다. 주로 초기 의도한 코드를 작성한 이후 이루어집니다.

리팩토링은 좋은 퀄리티의 코드를 위해서 빠질 수 없는 작업입니다. 초반 기능을 구현하기 바쁠 대에는 불필요해 보일 수 있어도, 장기적으로 봤을 때 반드시 이점을 볼 수 있는 작업이므로 되도록이면 개발 기간을 산정할 때, 리팩토링할 시간을 포함하는 것이 좋습니다.

4. 문서화(Documentations)

문서화는 개발에 대한 전반적인 내용을 문서로 기록하여 다른 사람들로 하여금 코드에 대한 이해를 돕는 작업인데요, 문서화가 문서를 작성하는 것만 한정하지는 않습니다.

4.1. 인라인 코멘트 (Inline Comments)

인라인 코드는 주석이라고도 하는데요, 코드 중간 중간 설명을 다는 행위를 뜻합니다. (파이썬에서는 #를 사용합니다) 특정 코드에 대한 설명을 달아 빠른 이해를 도울 수 있습니다.

주석은 복잡한 로직을 가지고 있는 코드 블럭의 경우, 주석을 통해 자연어로 설명하여 이해를 도울 수 있습니다. 또한 코드 자체가 어떠한 로직의 배경이나 이유, 영향을 받는 외부적인 요인 등을 설명하지 못할 때는 주석으로 설명하는 것이 효과적입니다.

4.2. 독스트링(Docstrings)

독스트링은 세개의 따옴표로 감싼 주석으로 함수나 모듈에 대한 설명을 작성할 때 사용됩니다.

  • One line docstring

    • 함수가 매우 간단할 경우, 아래와 같이 독스트링을 한 줄로 작성할 수 있습니다.
    • 예시)
      def female_ratio(female_count, total_count):
    """
    Calculate the ratio of female
    """
    return female_count / total_count

  • Multiline docstring

    • 다소 설명이 많이 필요한 경우에는 아래의 조건을 만족시키며 docstring의 내용을 확장할 수 있습니다.
      • argument에 대한 설명
      • argument의 타입 명시
      • 함수의 목적
      • 함수의 출력에 대한 설명
    • 예시)
      def female_ratio(female_count, total_count):
    """Calculate the ratio of female.

    Args:
    female_count: int. count of female.
    total_count: int. total count of people.

    Returns:
    female_ratio: female_count/total_count.
    """
    return female_count / total_count

Docstring에는 더욱 다양한 스타일에 대한 내용은 링크 를 참조하세요.

4.3. 프로젝트 문서

코드에 대한 문서 뿐만 아니라 전체 프로젝트에 대한 문서도 빠질 수 없습니다. 우리가 가장 쉽게 접할 수 있는 프로젝트 문서는 Github에서 종종 볼 수 있는 README.md 파일이죠. 프로젝트 문서는 프로젝트에 대한 개요, 의존성, 사용법, 디버깅 방법 등을 기술합니다.

효과적인 프로젝트 문서 작성 방식에 대한 내용은 Udacity에서 제공하는 무료 강의를 참조하실 수 있습니다.

마무리 하며

팀원이 많아지고 프로젝트의 단위가 커질 수록, 클린 코드는 권장사항이 아니라 필수인 것을 체감하고 있습니다. 그리고 클린코드는 습관인 것 같다는 생각이 듭니다. 기존의 습관을 떨쳐내기가 쉽지 않네요. 입사 초창기부터 가이드해줄 수 있는 시니어의 존재가 조직에 없었던 것이 참 아쉽게 다가오기도 합니다. 괜히 세상에 존재하지도 않는 그 분을 탓해보네요. (좋은 시니어나 멘토가 있다면 당신은 정말 축복받은 사람입니다!)

아무튼 주니어 분석가를 위한 클린코드에 대한 가이드를 나름대로 적어보았는데요, 처음 기획했던 것보다 다뤄야 할 내용이 다소 더 많아진 것 같습니다. 조금 더 공부하고 정리해서 다음에는 2편으로 돌아오겠습니다 :)

Reference

  • 파이썬 클린 코드
  • Udacity: Machine Learning DevOps Engineer