주석
1. 주석(Comments)
1.1 주석이란?
주석은 코드의 이해를 돕기 위해 가이드 역할을 하거나 코드의 특정 부분이 일시적으로 실행되지 않도록 하기 위해 사용됩니다. 코드만으로는 그 코드가 왜 작성되었는지, 무슨 목적으로 사용되는지를 전부 파악하기 어렵습니다. 그렇기 때문에 코드를 작성하거나 수정할 때 주석을 통해 코드의 주요 기능, 복잡한 로직의 동작 방식, 특별한 팁 등을 설명하고 메모하여 쉽게 파악할 수 있게 합니다.
특히, 코드를 처음 보거나 특정 부분의 코드를 오랜 시간 동안 보지 않았던 프로그래머도 주석 덕분에 쉽고 빠르게 코드를 이해하고 수정할 수 있습니다. 또한, 특정 코드 부분의 실행을 잠시 중단하고자 할 때도 주석을 활용하면 매우 유용합니다.
하지만, 주석이 많다고 해서 항상 좋은 것은 아닙니다. 과도한 주석은 코드의 가독성을 저하시킬 수 있으므로, 중요한 부분에만 적절하게 주석을 활용하는 것이 바람직합니다. 다음 장에서는 이러한 주석을 파이썬에서 어떻게 활용하는지, 그리고 주석을 효과적으로 작성하는 방법에 대해 자세히 알아보겠습니다.
주석은 꼭 서야 할까요?
파이썬은 생산성이 좋고 빠르게 코드를 작성할 수 있습니다. 그러다 보니 하루에도 수천 줄의 코드를 작성하는 일이 빈번합니다. 이렇게 빠르게 코드를 작성하다 보면 어제 작성한 코드도 낯설게 느껴지는 경우가 많습니다.
하지만 주석을 상세하게 작성하는 것은 코드의 생산성을 떨어뜨릴 수 있습니다. '기호지세(騎虎之勢)'라는 말이 있습니다. 호랑이를 타고 달리는 기세로 한 번 시작한 일을 그 기세를 유지하면서 진행한다는 뜻입니다. 여기서 이 호랑이가 파이썬과 같다고 종종 생각합니다. 한 번 코딩을 시작하면 멈출 수 없는 경우가 많기 때문입니다. 이때 주석을 작성하는 것이 흐름을 끊곤 합니다.
그렇기 때문에 필자는 프로젝트의 목적에 따라 주석을 관리합니다. 예를 들어 협업을 하지 않는 중요하지 않은 프로젝트의 경우 거의 주석을 작성하지 않습니다. 가독성이 높은 코드를 목표로 삼으면 굳이 주석을 작성하지 않아도 이해하는 데 문제가 생기지 않기 때문입니다.
하지만 협업을 하는 프로젝트의 경우, 흐름이 끊기더라도 상세하게 주석을 작성합니다. 저를 이어 다른 사람이 이 코드를 접하더라도 빠르게 이해할 수 있도록 매뉴얼도 작성하는 편입니다. 때로는 이 작업이 코드를 작성하는 시간보다 더 오래 걸리기도 합니다.
어느 정도로 상세하게 작성해야 할지 판단하기 어려울 때는 협업하는 팀원끼리 같은 코드를 보며(코드리뷰) 주석에 대한 약속(컨벤션)을 정하는 것이 좋습니다.
1.2 주석 생성
Python에서 주석은 코드의 일부분을 설명하거나 임시로 코드를 비활성화하기 위해 사용됩니다. 파이썬에서는 주석을 #, ''' 또는 """ 기호로 시작합니다. 이 기호 뒤에 있는 모든 텍스트는 주석으로 처리되며, 실행되지 않습니다.
1.2.1 한 줄 주석
한 줄 주석은 # 기호로 시작합니다. 이 기호 뒤에 따라오는 텍스트는 모두 주석으로 처리됩니다. 지금 실행하고 있는 환경이 colab이라면 아래처럼 입력하고 Alt + Enter를 눌러보세요. 그러면 Hello, World 1!과 Hello, World 2!가 출력된 것을 확인할 수 있습니다. 위니북스에서는 왼쪽 상단에 실행 버튼만 클릭하면 됩니다.
위 예제에서 첫 번째 줄은 완전한 주석이며, 두 번째 줄은 코드와 같은 줄에 주석이 있습니다. 두 경우 모두 # 기호 뒤의 텍스트는 실행되지 않습니다. 위에 있는 코드를 그대로 복사해서 새로운 코드 블록에 옮겨 놓습니다. 그리고 아래 코드를 주석 처리해 봅시다.
위 예제에서는 Hello, World 1!만 출력되고 Hello, World 2!는 출력되지 않습니다. 이처럼 주석을 사용하면 특정 코드 부분을 비활성화할 수 있습니다.
1.2.2 여러 줄 주석
여러 줄 주석은 ''' 또는 """ 기호를 사용하여 작성합니다. 이 기호들 사이에 있는 텍스트는 모두 주석으로 처리됩니다.
위 예제에서 첫 번째 세 줄은 주석으로 처리되어 실행되지 않으며, Hello, World!만 출력됩니다. 여러 줄 주석은 긴 설명이나 코드 블록을 임시로 비활성화할 때 유용합니다.
1.3 주석 작성 팁
코드에 주석을 작성하는 것은 중요하지만, 어떤 주석이 좋은 주석인지 알아야합니다. 좋은 주석은 코드의 이해를 돕고, 협업을 원활하게 만듭니다.
- 필요한 경우에만 작성: 주석은 필요한 경우에만 작성하세요. 너무 많은 주석은 오히려 코드의 가독성을 떨어뜨립니다.
- 명확하고 간결하게: 주석은 명확하고 간결하게 작성하세요. 길고 복잡한 주석은 피하는 것이 좋습니다.
- 일관성 유지: 주석 스타일과 위치는 일관성을 유지하세요. 프로젝트 전체에서 일관된 주석 스타일을 사용하는 것이 중요합니다.
- 중요한 부분에만 작성: 중요한 코드 블록이나 복잡한 로직 부분에 주석을 작성하세요. 일반적인 코드에는 주석이 필요하지 않습니다.
- 업데이트 주의: 코드가 변경될 때 주석도 함께 업데이트하는 것을 잊지 마세요. 오래된 주석은 혼란을 줄 수 있습니다.
어떤 주석이 좋은 주석인지 확인하려면 구글과 같은 글로벌 기업의 파이썬 코딩 스타일 가이드라인을 확인하시는 것이 좋습니다. 기업마다 주석 작성 방법에 대한 규칙이 같진 않지만 협업을 위해 어떻게 주석을 작성해야 하는지 배울 수 있습니다. 이렇게 회사에서 어떻게 코드를 짜야하는지를 약속한 것을 코딩컨벤션이라고 합니다. 아래 공개되어 있는 구글 파이썬 스타일 가이드를 참고해주세요.
google_python_styleguide주석은 설명과 코드를 보류하는 용도 외에도 라이센스나 작성자 정보, 코드와 관련된 전문적인 지식(예를 들어 법무 정보, 세금 정보), 코드태그(TODO, FIXME), 실행 환경을 지정하는 매직 주석, 문서화를 위한 독스트링 등을 작성할 때도 사용됩니다.
더 상세한 내용은 Chapter16 파이썬 컨벤션 파트에서 다루도록 하겠습니다.