목적
- 주석 관련한 내용은 절대적인 규칙이 없습니다.
- 다른 좋은 툴이 있다면, 해당 툴로 대체되어도 좋습니다.
- 주석으로 인해 개발 중인 소스 코드에 대한 이견이 있을 수 있습니다.
- 반면 라이브러리 동작 등의 개발 방법을 알수 없는 경우 주석은 효과적인 방안이 될 수 있습니다.
- 아래 예시 들은 주석이 혼란을 야기하는 몇가지 사례를 설명하겠습니다.
비즈니스에 논리 복잡성이 있는 것만 언급
- 주석은 프로그래머가 이해하기 어려운 비즈니스 로직을 설명하는데 도움을 주기 위한 목적으로 사용합니다.
- 주석은 알고리즘을 설명하지 않습니다.
- 좋은 코드는 일반적으로 자체가 문서가 되어야 하며, 소스 코드는 읽을 때 이해가 되어야 한다고 생각합니다.
- 그러나 때때로 개발자로써 우리가 모르는 특정 비즈니스 로직에 맞게 설계된 경우가 있습니다.
function convert(data){
let result = 0;
const length = data.length;
for (let i = 0; i < lenght; i++){
const char = data.charCodeAt(i);
result = (result << 5) — result + char;
result &= result;
}
}
- 로직내 comment로 인해서 노이즈 생성의 여지가 있습니다.
function convert(data) {
let result = 0;
const length = data.length;
for (let i = 0; i < length; i++){
const char = data.charCodeAt(i);
result = (result << 5) — result + char;
result &= result;
}
}
저널 주석을 피합니다.
- 주석은 시간이 지남에 따른 히스토리 기록 용도의 임의 저널로 생성되곤 합니다.
- 버전 제어 도구가 없었기 때문에 과거에는 유용한 작업이었습니다.
- 오늘날 이 작업은 버전 관리 소프트웨어에 위임되어야 합니다. (Git 사용을 권장합니다.)
- 따라서 데드 코드, 주석 처리된 코드, 저널 주석이 필요하지 않습니다.
- git log를 사용하여 history 명령을 가져와야 합니다.
function add(a, b) {
return a + b;
}
function add(a, b) {
return a + b;
}
위치를 생성하는 마커를 지양합니다.
- 위치 생성 마커는 일반적으로 노이즈를 생성합니다.
- 함수 및 변수 이름과 적절한 식별 및 형식을 사용하여 코드에 시각적 구조를 부여해야 합니다.
- 다음 예시는 위치 마커와 클린한 버전의 예제를 보여줍니다.
controller.model = {
name: ‘Felipe’,
age: 34
};
const actions = function() {
};
controller.model = {
name: ‘Felipe’,
age: 34
};
const actions = function() {
};