Creating sample code

좋은 샘플 코드는 correct 하고 concise 하여 독자들이 빠르게 이해하고 최소한의 사이드 이펙트와 함께 쉽게 사용할 수 있는 코드를 의미합니다.

Correct

샘플 코드는 아래 기준을 만족해야 합니다:

• 에러 없이 빌드됩니다.
• 하고자 하는 바를 수행할 수 있어야 합니다.
• 가능한 한 실제 환경에서 사용 가능해야 합니다. 예를 들어, 코드는 보안 취약점을 포함해서는 안 됩니다.
• 언어별 컨벤션을 따라야 합니다.

샘플 코드는 사용자들이 코드를 쓰는 방식에 직접적으로 영향을 끼치기 때문에 당신의 제품을 사용하는 최고의 방식을 제시할 수 있어야 합니다. 만약 특정 작업을 수행하는 방식이 하나 이상이라면, 당신의 팀에서 최고라고 판단한 방식을 작성하세요. 만약 그것을 따져보지 못했다면, 시간을 갖고 검토하세요.

항상 샘플 코드를 테스트하세요. 시간이 흐름에 따라 시스템이 변화하기 때문에 샘플 코드 역시 오류를 가질 수 있습니다. 테스트를 준비하고, 다른 코드를 다루듯 샘플 코드도 다루세요.

많은 팀이 단위 테스트를 샘플 프로그램으로서 다룹니다. 하지만 단위 테스트는 테스트일 뿐이고, 샘플 프로그램의 유일한 목적은 가르치는 것입니다.

Snippet이란 하나 또는 몇 안되는 라인의 샘플 프로그램입니다. Snippet 으로 가득찬 문서는 시간에 따라 품질이 떨어지는데, 대부분의 팀들은 샘플 프로그램 전체보다 snippet 은 테스트 하지 않는 경향이 있기 때문입니다.

Running sample code

좋은 문서는 샘플 코드를 실행시키는 방법을 설명합니다. 예를 들어, 샘플 코드를 실행하기 전에 아래 행동을 취해야 할 수도 있습니다:

• 특정 라이브러리 설치
• 환경 변수 값 수정
• IDE의 어떠한 설정 변경

샘플 코드의 실행 결과나 출력을 묘사하는 것을 검토하세요. 특히 샘플 코드가 실행시키기 어려울 때에는 더더욱 그렇습니다.

Concise

샘플 코드는 짧게, 그리고 꼭 필요로 하는 구성요소만 포함해야 합니다. 만약 초급 C 프로그래머가 malloc 함수를 호출하는 방법을 배우려 할때, 간단히 코드 스니펫만 주면 됐지, 리눅스의 소스 트리 전체를 줄 필요는 없습니다. 그렇다 하더라도, 코드를 짧게 유지하기 위해 나쁜 사용 사례를 이용하면 안 됩니다; 항상 정확함이 간결함보다 우선시되어야 합니다.

Understandable

명확한 샘플 코드를 만들기 위해 아래 권장사항을 따르세요:

• descriptive 한 클래스, 메소드, 변수 이름을 사용하세요.
• 알아보기 힘든 프로그래밍 트릭을 이용하여 독자들을 혼란시키지 마세요.
• 깊게 중첩된 코드는 피하세요.
• 샘플 코드의 특정 부분을 강조하기 위해 볼드체나 색상이 있는 폰트를 사용하세요. 하지만 하이라이팅은 신중히 사용하세요. 너무 많은 하이라이팅은 가독성에 영향을 줍니다.

Commented

샘플 코드의 주석 관련하여 아래 권장사항을 따르세요:

• 주석은 짧게, 하지만 명료성을 간결성보다 우선시하세요.
• 자명한 코드에 주석을 작성하지 마세요. 하지만 전문가인 당신에게 자명한 것이 신입에게는 그렇지 않을 수 있음을 기억하세요.
• 직관적이지 않은 코드에 주석을 작성하는 것을 집중하세요.
• 독자들이 기술에 익숙할 경우 코드가 무엇을 하는지 주석으로 설명하지 말고, 코드 자체가 자신을 설명하도록 하세요.

독자들이 코드를 복사/붙여넣기 할 때 주석까지 따라감을 기억하세요. 반면 길고 복잡한 개념을 설명해야 할 때, 샘플 프로그램 전에 텍스트로서 작성하세요.

만약 코드를 이해하기 쉽게 하기 위해 간결하게 작성하여 조금의 production readiness 를 희생해야 한다면, 주석을 통해 이 결정에 대해 충분히 설명하세요.

Reusable

사용자들이 샘플 코드를 재사용하기 쉽도록 하려면, 아래 항목들을 제공하세요:

• 샘플 코드를 실행시키기 위한 모든 정보(설정과 디펜던시 포함).
• 코드가 유용하게 확장되거나 커스터마이즈 될 수 있는 방법.

샘플 코드가 독자의 앱을 부숴버리는 경험을 선사하는 것은 좋지 않습니다. 따라서 샘플 코드를 작성할 때, 해당 코드가 다른 프로그램에 통합되었을 때 발생할 수 있는 잠재적인 부작용을 반드시 고려하세요.

The example and the anti-example

독자들에게 가끔은 무엇을 하면 안 되는지 알려주는 것도 가끔은 나쁘지 않습니다. 예를 들어, bash 와 같은 언어들에서는 =와 같은 문자 사이에 공백 문자를 사용할 수 없습니다. 이러한 경우에는 좋은 예시와 잘못된 예시를 보여주는 것이 독자들에게 도움이 될 수 있습니다. 예를 들어:

# 유효한 문자열 할당.
s="The rain in Maine."

# `=` 양족에 공백 문자가 들어가 있어 유효하지 않은 문자열 할당.
s = "The rain in Maine."

Sequenced

좋은 샘플 코드는 다양한 난이도를 가집니다.

샘플 코드 세트에서 가장 첫 번째이자 기본적인 예제는 보통 "Hello World" 프로그램이라고 불립니다. 기본을 익힌 후에는 더 복잡한 프로그램을 원하는 엔지니어들이 많습니다. 따라서, 좋은 샘플 코드 세트는 간단한 코드, 중간 난이도의 코드, 그리고 복잡한 코드가 균형 있게 포함되어 있어야 합니다.