06. 주석과 코딩 스타일 - 읽기 좋은 코드 만들기

주석과 코딩 스타일

06. 주석과 코딩 스타일 - 읽기 좋은 코드 만들기

코드는 기계만 읽는 게 아니다. 미래의 나, 그리고 함께 일하는 동료도 읽는다. "돌아가기만 하면 됐지" 하고 넘기면 나중에 반드시 후회한다. 오늘은 주석과 코딩 스타일을 배워보자.

---

주석이란?

주석(Comment)은 코드 안에 적는 설명글이다. 파이썬은 주석을 완전히 무시하고 실행하지 않는다. 오로지 사람을 위한 글이다.

주석의 역할

 

한 줄 주석

# 뒤에 적는다.

# 사용자의 나이를 입력받는다
age = int(input("나이: "))

# 성인 여부 판단
if age >= 19:
    print("성인입니다")    # 19세 이상이면 성인

# print("이 줄은 실행되지 않는다")

#부터 그 줄의 끝까지가 주석이다. 코드 뒤에 붙여도 되고, 줄 전체를 주석으로 만들어도 된다.

여러 줄 주석

파이썬에는 공식적인 여러 줄 주석 문법이 없다. 대신 두 가지 방법을 쓴다.

# 방법 1: # 여러 개 (권장)
# 이 프로그램은 사용자에게 이름과 나이를 입력받아
# 인사말을 출력하는 간단한 프로그램이다.
# 작성일: 2026-02-21

# 방법 2: 삼중 따옴표 (비공식)
"""
이것도 여러 줄 주석처럼 쓸 수 있다.
하지만 엄밀히 말하면 문자열이지 주석은 아니다.
함수나 클래스 설명(docstring)에 주로 쓴다.
"""

💡 팁: 삼중 따옴표는 나중에 배울 독스트링(docstring)에서 공식적으로 사용한다. 일반 주석에는 #을 쓰는 것이 파이썬 관례다.

---

좋은 주석 vs 나쁜 주석

주석을 많이 달면 좋은 게 아니다. 필요한 곳에 적절한 주석을 다는 게 중요하다.

나쁜 주석 - 코드를 그대로 반복

# age에 25를 저장한다
age = 25

# age를 출력한다
print(age)

# 1을 더한다
age = age + 1

코드를 읽으면 바로 알 수 있는 내용을 굳이 주석으로 적을 필요 없다.

좋은 주석 - "왜" 그렇게 했는지 설명

# 한국 기준 만 19세부터 성인
ADULT_AGE = 19

# API 응답 시간이 느려서 타임아웃을 10초로 늘림 (기본값 3초)
TIMEOUT = 10

# 윤년 계산: 4로 나눠지되 100으로 안 나눠지거나, 400으로 나눠지면 윤년
is_leap = (year % 4 == 0 and year % 100 != 0) or (year % 400 == 0)

좋은 주석	나쁜 주석
코드만으로 알 수 없는 의도를 설명	코드를 그대로 한글로 번역
왜 이렇게 했는지 이유를 적음	무엇을 하는지만 적음
복잡한 로직에 대한 요약	누가 봐도 당연한 코드에 달린 주석
TODO, FIXME 같은 표시	오래되어 코드와 맞지 않는 주석

유용한 주석 태그

# TODO: 나중에 에러 처리 추가하기
# FIXME: 윤년 계산이 가끔 틀림 - 확인 필요
# HACK: 임시 해결책, 나중에 리팩토링
# NOTE: 이 함수는 음수를 처리하지 않음

---

PEP 8 - 파이썬 코딩 스타일 가이드

PEP 8은 파이썬 공식 코딩 스타일 가이드다. "이렇게 쓰면 읽기 좋다"는 권장 사항을 모아놓은 것이다.

PEP 8 핵심 규칙 5가지

💡 PEP는 "Python Enhancement Proposal"의 약자다. 파이썬을 개선하자는 제안서인데, 그중 8번째가 코딩 스타일에 관한 것이라 PEP 8이다.

1. 들여쓰기: 스페이스 4칸

# 좋은 예
if age >= 19:
    print("성인")
    if age >= 65:
        print("경로 우대")

# 나쁜 예 - 2칸, 탭 혼용 등
if age >= 19:
  print("성인")     # 2칸 - 비권장

파이썬은 들여쓰기가 문법의 일부다. 스페이스 4칸이 공식 표준이다. VS Code 같은 에디터에서는 Tab 키를 누르면 자동으로 4칸이 들어간다.

2. 한 줄 최대 79자

한 줄이 너무 길면 읽기 어렵다. PEP 8에서는 79자를 권장한다.

# 너무 긴 줄 - 읽기 어려움
result = first_value + second_value + third_value + fourth_value + fifth_value + sixth_value

# 줄바꿈으로 정리
result = (first_value + second_value
          + third_value + fourth_value
          + fifth_value + sixth_value)

💡 실전에서는 79자를 꼭 지키진 않는다. 100자~120자 정도를 기준으로 삼는 팀이 많다. 중요한 건 "팀 내 일관성"이다.

3. 빈 줄 사용

# 함수 사이에 빈 줄 2개
def greet(name):
    print(f"안녕, {name}!")


def farewell(name):
    print(f"잘가, {name}!")


# 코드 블록 사이에 빈 줄 1개
age = 25
name = "홍길동"

print(f"{name}은 {age}세")

4. 공백 규칙

# 좋은 예
x = 10
y = x + 5
my_list = [1, 2, 3]
result = func(a, b)

# 나쁜 예
x=10
y = x+5
my_list = [1,2,3]
result = func (a,b)

규칙	좋은 예	나쁜 예
= 양쪽에 공백	x = 10	x=10
연산자 양쪽에 공백	y = x + 5	y = x+5
쉼표 뒤에 공백	[1, 2, 3]	[1,2,3]
함수 호출 괄호 앞 공백 없음	print(x)	print (x)
괄호 안쪽에 공백 없음	func(a, b)	func( a, b )

---

네이밍 규칙 (이름 짓기)

변수, 함수, 클래스 등의 이름을 짓는 규칙이다. 이름만 봐도 무엇인지 짐작할 수 있어야 한다.

변수와 함수: snake_case

단어 사이를 밑줄(_)로 연결하고, 전부 소문자로 쓴다.

# 좋은 예 (snake_case)
user_name = "홍길동"
total_score = 95
is_valid = True

def calculate_average(scores):
    return sum(scores) / len(scores)

# 나쁜 예
UserName = "홍길동"      # PascalCase - 클래스용
totalScore = 95          # camelCase - 자바 스타일

상수: UPPER_SNAKE_CASE

변하지 않는 값은 전부 대문자로 쓴다.

MAX_RETRY = 3
PI = 3.14159
DATABASE_URL = "localhost:5432"

클래스: PascalCase

단어의 첫 글자를 대문자로 쓴다. (26편에서 배운다)

class StudentInfo:
    pass

class ShoppingCart:
    pass

네이밍 규칙 정리

대상	규칙	예시	별칭
변수, 함수	소문자 + 밑줄	user_name	snake_case
상수	대문자 + 밑줄	MAX_RETRY	UPPER_SNAKE_CASE
클래스	단어 첫 글자 대문자	StudentInfo	PascalCase
비공개(내부용)	밑줄로 시작	_internal_var	-

---

의미 있는 이름 짓기

네이밍 규칙보다 더 중요한 건 의미가 드러나는 이름을 짓는 것이다.

# 나쁜 예 - 무슨 뜻인지 모르겠다
a = 25
b = "홍길동"
c = True
d = [80, 90, 95]

# 좋은 예 - 이름만 봐도 알겠다
age = 25
name = "홍길동"
is_student = True
scores = [80, 90, 95]

# 나쁜 예 - 약어 남발
def calc(s):
    return sum(s) / len(s)

# 좋은 예 - 읽기 쉽다
def calculate_average(scores):
    return sum(scores) / len(scores)

💡 팁: 이름은 좀 길어도 괜찮다. n보다 student_count가 낫고, calc보다 calculate_average가 낫다. 코드는 쓰는 시간보다 읽는 시간이 훨씬 길다.

---

코드 주석 달기 실습

나쁜 코드를 좋은 코드로 바꿔보자.

Before (나쁜 코드)

a = int(input("숫자: "))
b = int(input("숫자: "))
c = a + b
d = a - b
e = a * b
f = a / b
print(c)
print(d)
print(e)
print(f)

After (좋은 코드)

# 두 숫자의 사칙연산 결과를 출력하는 프로그램

first_number = int(input("첫 번째 숫자: "))
second_number = int(input("두 번째 숫자: "))

addition = first_number + second_number
subtraction = first_number - second_number
multiplication = first_number * second_number
division = first_number / second_number

print(f"덧셈: {first_number} + {second_number} = {addition}")
print(f"뺄셈: {first_number} - {second_number} = {subtraction}")
print(f"곱셈: {first_number} * {second_number} = {multiplication}")
print(f"나눗셈: {first_number} / {second_number} = {division:.2f}")

변수 이름만 잘 지어도 주석이 거의 필요 없어진다. 이것이 "좋은 코드는 주석이 필요 없다"라는 말의 뜻이다.

---

직접 해보기

문제 1. 아래 코드에서 PEP 8 위반 사항을 모두 찾아 수정해보자.

x=10
y= 20
z =x+y
my_list=[1,2,3,4,5]
print ( z )
print( my_list )

문제 2. 아래 코드의 변수 이름을 의미 있게 바꿔보자.

a = "파이썬 독학"
b = 33
c = 0

for i in range(b):
    c += 1
    print(f"{a} - {c}편 작성 완료")

문제 3. 아래 코드에 적절한 주석을 달아보자. (코드를 그대로 번역하지 말고 "왜"를 설명하자)

password = input("비밀번호: ")
if len(password) < 8:
    print("비밀번호가 너무 짧습니다.")
elif password.isdigit():
    print("숫자만으로는 안전하지 않습니다.")
else:
    print("비밀번호가 설정되었습니다.")

정답 보기

# 문제 1 - PEP 8 수정
x = 10
y = 20
z = x + y
my_list = [1, 2, 3, 4, 5]
print(z)
print(my_list)
‍
# 문제 2 - 의미 있는 변수명
blog_title = "파이썬 독학"
total_posts = 33
completed = 0
‍
for post_number in range(total_posts):
    completed += 1
    print(f"{blog_title} - {completed}편 작성 완료")
‍
# 문제 3 - 적절한 주석
# 비밀번호 보안 규칙 검사
password = input("비밀번호: ")
‍
# 최소 8자 이상이어야 무차별 대입 공격에 안전
if len(password) < 8:
    print("비밀번호가 너무 짧습니다.")
# 숫자만으로는 조합이 적어 쉽게 뚫림
elif password.isdigit():
    print("숫자만으로는 안전하지 않습니다.")
else:
    print("비밀번호가 설정되었습니다.")

---

오늘의 정리

항목	내용
주석	#으로 시작. "왜"를 설명하는 주석이 좋다
PEP 8	파이썬 공식 코딩 스타일 가이드
들여쓰기	스페이스 4칸이 표준
네이밍	변수/함수: snake_case, 상수: UPPER_CASE, 클래스: PascalCase
핵심 원칙	이름을 잘 지으면 주석이 줄어든다. 코드는 읽는 시간이 더 길다

---

다음 편 예고: 조건문 - if, elif, else

드디어 프로그램에 "판단력"을 부여한다! "만약 ~라면", "아니면 ~라면", "그것도 아니면"... 조건에 따라 다르게 동작하는 코드를 만들어보자. Part 2 흐름 제어의 시작이다.

---

태그: 파이썬 Python 파이썬독학 주석 PEP8 코딩컨벤션 네이밍규칙 클린코드 파이썬기초 IT교육