Coding Style Guide — 스타일 가이드

코드는 쓰는 시간보다 읽히는 시간이 훨씬 길다. 한 번 개발된 코드는 수명주기 동안 수백 차례 읽힌다. 여러 사람이 하나의 코드베이스에서 작업하는 환경에서, 코드를 어떻게 작성할지에 대한 합의된 규칙이 없으면 혼란이 불가피하다. 스타일가이드는 이 문제를 해결한다.

좋은 소프트웨어 코드의 6가지 공통점

1. 쉽게 읽을 수 있다 (가독성이 높다)

5분 이내에 개발자의 의도를 이해할 수 없는 코드는 좋은 코드가 아니다. 컴퓨터와 달리 사람은 변수의 이름이나 줄 간격을 고려한다. 한 번 개발된 코드는 수명주기 동안 수백 차례 읽힌다. 코드의 가독성을 높이기 위해 의미 있는 변수 이름을 사용해야 하고, 간격을 삽입하거나 적절한 코드 구조를 표현하기 위해 들여쓰기를 해야 한다.

2. 주석이 잘 작성되어 있다

루프가 뭔지 말해주는 주석은 필요 없다. 대신에 코드가 제공하는 기능, 즉 왜 필요한가를 말해주는 주석이 필요하다. 좋은 코드에는 개발자가 코드를 개발한 목적을 설명하는 주석이 항상 존재한다.

주석의 장점과 단점:

3. 코드구조가 간결하다

코드를 간결하게 만들면 버그를 줄일 수 있다. 코드의 복잡성이 높아지면 버그의 수도 많아질 수 있다는 상관관계가 통계적으로 입증되어 있다. 각 코드가 각자의 기능을 훌륭히 수행하고, 다음 코드가 다른 기능을 수행하도록 프로그램을 만들어야 한다. 가장 간단한 솔루션이 최상의 솔루션이다.

코드를 지나치게 중복해서 사용하는 것을 경계해야 한다. 1,000줄의 함수를 관리하는 것이 ‘악몽’ 같다. 짧지만 확실하게 한 가지 기능을 수행하도록 만들어야 한다.

4. 변경에 탄력적이다

현재 필요한 사항, 미래에 필요할 수 있는 사항 모두를 염두에 둔 소프트웨어가 좋은 소프트웨어이다. 최소한의 수정으로 미래에 필요한 사항을 수용할 수 있도록 탄력적인 소프트웨어를 개발할 수 있어야 한다.

5. 활용을 위해 관리할 수 있어야 한다

관리성이란 어떤 코드라도 삭제되거나 무시되는 일 없이 추후 활용될 수 있게 관리 되어야 한다는 것이다. 소프트웨어 코드 내에 URL, 액세스 키, 데이터베이스 비밀번호, 특정 사용자의 IP 주소 등을 직접 하드 코딩하는 방식으로 소프트웨어를 개발해선 안 된다. 개발자가 자신의 코드를 관리할 수 없다면 모듈화가 충분히 이루어지지 않은 코드이다.

6. 제 기능을 해야 한다

코드 배포 전에 충분히 제 기능을 수행하는지 점검해야 한다. 아무리 좋게 보이는 코드라도 제 기능을 못하면 좋은 코드가 아니다.

좋은 코드 작성을 위한 규칙

최적화보다는 가독성이 우선이다

가독성이 높은 코드를 만들기 위해서는 모듈화 개념이 잘 반영된 코드 작성이 필요하다.

아키텍처를 우선 개발하라

아키텍처 설계 없이 코드를 개발한 경우 대개 코드의 구조적인 문제가 발생한다. 코드를 작성하기 전에 선행해야 할 작업(코드 사용 방법, 모듈화 방법, 서비스 동작 방법, 구조, 테스트 및 디버깅 방법, 업데이트 방법들)을 먼저 생각하고 이해해야 한다.

간단하고 단순하게 코딩하라

KISS(Keep It Simple and Stupid) 원리를 지켜야 한다. 코드를 단순하고 간단하게 작성 시 버그가 줄어들고 디버깅 시간도 줄일 수 있다. 불필요한 추상화 및 패턴 적용 없이 필요한 일만 수행하도록 코드를 작성해야 한다. 추상화나 패턴을 적용하면 코드에 대한 가독성이 높아지고 유지보수가 쉬워질 수 있으나, 과도하게 적용하면 오히려 코드가 더 복잡해진다.

주석을 작성하되 보조적으로 사용하라

좋은 코드는 주석이 없어도 이해가 되는 코드이다. 물론 그렇다고 하더라도 기능에 대한 충분한 설명은 필요하다 (예: 클래스 별로 해당 클래스가 어떠한 일을 하는지에 대한 설명). 메서드의 정의와 사용법을 설명하는 한 줄 짜리 간단한 주석(문서화) 작성도 유용하다.

스타일가이드란?

프로그래밍 스타일가이드란 코드를 ‘어떻게 작성할지’에 대한 전반적인 규칙을 담은 문서이다. 코드 컨벤션(Code Convention)이라고도 한다.

복잡한 문제를 간결하고 사람이 읽기 쉬운 코드로 작성해 해결하는 것이 소프트웨어 엔지니어로서 필수적인 기술이며, 좋은 코드 스타일은 이런 기술을 연마하는 데 큰 도움을 준다.

각 소프트웨어 조직은 코드를 읽기 쉽고 유지보수하기 쉽게 작성하기 위한 자체 코딩 표준 또는 “스타일가이드”를 갖고 있다. 스스로 속한 조직의 코딩 표준을 배우고 따르는 것이 필요하다. 팀원 전체가 동일한 스타일가이드를 따라 코드를 작성하면, 누가 코드를 작성했는지에 관계없이 동일한 스타일의 코드를 만들 수 있다.

단, 프로그래밍 스타일가이드는 불변의 법칙도 아니고 또한 예외 없이 지켜야 하는 법칙 또한 아니다. 최고의 스타일가이드라는 것은 정의할 수 없다.

스타일가이드에서 다루는 내용들

• 일반적인 이름 규칙, 파일 이름, 타입 이름
• 변수 이름 (일반적인 변수 이름, 상수 이름, 함수 이름, 네임 스페이스 이름, 매크로 이름)
• 주석 (일반적인 주석 스타일, 클래스에 관한 주석, 함수에 관한 주석, TODO 주석)
• 기타 여러가지 사항들 (들여쓰기, 줄 바꿈 등)

스타일가이드 코드 예시

위 예시에서 확인할 수 있는 주요 규칙:

• 함수 이름과 괄호 및 인자 사이에는 공백 없음: pow(int x, int n)
• 공백 4칸으로 들여쓰기 (탭 금지)
• 매개변수 사이에 공백 한 칸 씩
• 연산자 앞 뒤에 공백 한 칸 씩: result *= x;
• 논리적으로 다른 블록은 한 줄 띄어쓰기
• 프로그램 구조를 단순화, 중첩된 조건문 최대한 배제하기
• 세미콜론 필수
• for/if/while 뒤에 공백 한 칸 씩: for (int i = 0; ...)
• 한 줄은 너무 길지 않게

구글 C++ 스타일가이드

구글에서 오픈소스로 관리하고 있는 C++ 스타일가이드이다. C++을 배우기 위한 자료가 아니라, 코드 작성 규칙을 정의하는 문서이다.

• 내부적으로 네 명의 구글 소프트웨어 엔지니어가 관리를 해 주고 있다
• 제안은 누구나 가능하고, 다수결이 아닌 협의제로 운영된다
• 자명한 경우에 있어서는 생략 되어 있는 경우도 많다 (예: “goto를 사용하지 말아라”)
• 구글 내부 모든 소스코드들이 C++ 스타일가이드를 지키지는 않고 있다
• 스타일가이드는 느리지만 꾸준히 변하며, 기존 스타일가이드에 맞춘 코드들을 굳이 수정하여 변경하려고 하지 않는다
• 팀의 스타일가이드가 존재한다면 팀의 스타일가이드를 더 중시한다 (예: Chromium 팀, 안드로이드 팀)

주요 섹션: Header Files, Scoping, Classes, Functions, Naming, Comments, Formatting 등

구글 C++ 스타일가이드 예시 — #define 가드

모든 헤더 파일은 여러 번 포함되지 않도록 하기 위한 #define 가드를 가져야 한다. 이 심볼 이름의 형식은 <프로젝트>_<경로>_<파일>_H_ 여야 한다.

// foo/src/bar/baz.h 파일의 경우:
#ifndef FOO_BAR_BAZ_H_
#define FOO_BAR_BAZ_H_
...
#endif  // FOO_BAR_BAZ_H_

Chromium C++ 스타일가이드

구글 C++ 스타일가이드를 기반으로 하되, 예외 사항에 대해 추가로 정의한 팀 전용 스타일가이드이다. Chromium 프로젝트에서 사용한다.

기타 스타일가이드

스타일가이드는 C++에만 국한되지 않는다. 다양한 언어에 대한 스타일가이드가 존재한다:

• Java: Google Java Style Guide, Oracle Code Conventions for the Java Programming Language
• Python: PEP 8 — Style Guide for Python Code, Google Python Style Guide
• JavaScript: Google JavaScript Style Guide, Airbnb JavaScript Style Guide