마크다운에서 코드 표현하기
프로그래밍 문서에서 코드는 매우 중요한 부분이에요. 마크다운은 코드를 효과적으로 표현할 수 있는 여러 방법을 제공해요. Awesome Design을 적용하면 코드를 더욱 읽기 좋게 표현할 수 있어요.
좋은 코드 표현은 개발자들이 문서를 이해하는 속도를 크게 높여요. 문법 강조, 라인 번호, 주석 등을 활용해서 복잡한 코드도 쉽게 이해할 수 있게 만들 수 있답니다.
기본 코드 블록 작성
인라인 코드
한 줄 짜리 코드는 백틱 사이에 넣으면 돼요. 예를 들어 `const x = 5;` 같은 짧은 코드 조각을 표현할 때 사용해요. 이 방식은 문장 중간에 변수명이나 함수명을 표현할 때 유용해요.
코드 블록
여러 줄의 코드는 삼중 백틱(“`)으로 감싸면 돼요. 코드 블록 시작 바로 옆에 언어명을 지정하면 문법 강조(syntax highlighting)가 적용돼요. JavaScript, Python, Java 등 다양한 언어를 지원해요.
코드 블록 내 사용자 정의
언어별 문법 강조
코드 블록에서 언어를 지정하면 해당 언어의 문법에 맞춰 색상이 자동으로 적용돼요. 키워드는 파란색, 문자열은 초록색 같은 식으로 표현되니까 코드가 훨씬 읽기 쉬워져요.
라인 번호 추가
일부 렌더러는 코드 블록에 라인 번호를 자동으로 추가해요. 긴 코드에서 특정 라인을 참고할 때 매우 유용해요. 문서에서 “9번 줄을 보세요”라고 하면 독자가 쉽게 찾을 수 있죠.
특정 라인 강조
일부 고급 마크다운 렌더러는 특정 라인을 강조할 수 있어요. 가장 중요한 부분을 하이라이트하면 독자의 주의를 끌 수 있어요.
코드에 주석 달기
한줄 주석
코드 내에 한 줄 주석을 추가해서 해당 라인의 의도를 설명해요. Python의 #, JavaScript의 //같은 언어별 주석 문법을 사용하면 코드 렌더러가 이를 인식하고 다른 색으로 표현해요.
블록 주석
여러 줄을 설명해야 할 때는 블록 주석을 사용해요. 복잡한 알고리즘이나 특이한 구현 방식을 설명할 때 효과적이에요.
참고 주석
코드 다음에 마크다운 텍스트로 추가 설명을 달 수도 있어요. “위 코드의 주의사항:” 같은 헤더를 붙여서 설명하면 코드와 설명이 명확히 구분돼요.
좋은 코드 예제 작성법
완전성
코드 예제는 독자가 실제로 실행해볼 수 있을 정도로 완전해야 해요. 필요한 import 문이나 초기화 코드를 빠뜨리면 안 된다는 뜻이에요. “이건 예시일 뿐이라서 실행 안 될 수 있다”는 식의 핑계는 피해야 해요.
단순성
예제는 핵심만 보여줘야 해요. 불필요한 부분을 포함하면 오히려 독자를 혼란스럽게 해요. 한 번에 여러 개념을 설명하려고 해도 각 개념마다 따로따로 예제를 만드는 게 낫습니다.
관련성
문서에서 설명한 내용과 실제 코드 예제가 정확히 일치해야 해요. “설명과 다른 코드”는 독자를 혼란스럽게 하고 신뢰도를 떨어뜨려요.
Claude와 함께 코드 작성
코드 작성 프롬프트
Claude에게 코드를 작성하도록 요청할 때는 구체적으로 지정하세요. “Python 함수를 만들어줘”보다 “리스트의 중복을 제거하는 Python 함수를 만들어주고, 예제와 설명도 포함해줘”같은 식의 요청이 낫습니다.
마크다운 형식 지정
Claude에게 “코드는 마크다운 코드 블록으로 감싸주고, 각 함수 위에 설명을 달아줘”같은 형식 지침을 주세요. 그럼 바로 사용 가능한 형식으로 받을 수 있어요.
점진적 개선
첫 버전이 마음에 안 들면 “더 간단하게”, “더 효율적으로”, “다른 방식으로” 같은 요청으로 반복 개선할 수 있어요.
다양한 프로그래밍 언어의 코드
Python 코드
Python은 들여쓰기가 문법 구조의 일부라서 마크다운에서 표현할 때 특히 신경을 써야 해요. 들여쓰기가 정확하지 않으면 코드가 실행되지 않을 테니까요.
JavaScript/TypeScript 코드
웹 개발 관련 문서에서 자주 나오는 언어들이에요. async/await, promise 같은 비동기 처리가 중요한 개념이니까 이런 부분을 명확하게 표현해야 해요.
SQL 쿼리
데이터베이스 문서에서 SQL 쿼리는 매우 중요해요. 길고 복잡한 쿼리는 여러 줄로 나누고, WHERE 조건 등을 명확히 표현해야 해요.
코드 예제의 구조화
점진적 예제
기본 예제에서 시작해서 점점 복잡한 예제로 진행하는 것이 좋아요. 독자가 단계적으로 개념을 이해할 수 있기 때문이에요.
좋은 예와 나쁜 예
“이렇게 하지 마세요”라는 나쁜 예제를 보여주고, “이렇게 하세요”라는 좋은 예제를 보여주는 것도 효과적이에요. 대비를 통해 학습 효과가 높아져요.
실행 결과 표시
코드 다음에 코드를 실행했을 때의 결과를 보여주세요. 이렇게 하면 독자가 코드의 효과를 직관적으로 이해할 수 있어요.
에러 처리 및 주의사항
흔한 실수 설명
새로운 개발자들이 자주 하는 실수를 미리 설명해주는 것도 좋아요. “초보자 함정: 변수명을 헷갈리기 쉽다”같은 주의사항을 달아두면 오류를 줄일 수 있어요.
에러 메시지 예제
잘못된 코드를 실행했을 때 나오는 에러 메시지를 보여주면, 독자들이 실제로 그런 에러를 마주쳤을 때 쉽게 이해할 수 있어요.
코드 문서화 표준
주석 스타일 통일
문서 전체에서 주석 스타일을 통일해야 해요. 어떤 코드는 한국어, 어떤 코드는 영어로 주석을 다는 식의 불일치는 피해야 해요.
네이밍 컨벤션
변수명, 함수명 등의 네이밍 방식을 일관성 있게 유지해야 해요. camelCase, snake_case 등을 섞으면 읽기 혼란스러워요.
결론
좋은 코드 문서는 단순히 코드를 보여주는 것이 아니에요. 주석, 설명, 예제, 실행 결과를 모두 조화롭게 표현해야 독자가 쉽게 이해할 수 있어요. Claude와 협력하면 이 모든 과정을 훨씬 더 효율적으로 진행할 수 있답니다!
지금부터라도 마크다운에서 Awesome Design 원칙을 적용해서 코드 문서를 작성해보세요. 독자들의 만족도가 크게 높아질 거예요!