Medium - The junior developer's guide to writing super clean and readable code

17 Jul 2019 in Trend

원문 - Chris Blakely

Trend 파악을 Medium 기고문 요약 포스팅 - 신입을 위한 깔끔하고 가독성 좋은 코드를 작성하는 가이드

코드를 작성하는건 쉬운 일이지만 가독성 좋고 깔끔한 코드를 작성하는 건 전혀 다른 일입니다. 그렇다면 깔끔한 코드는 무엇일까요? 저는 당신이 깔끔한 코드를 작성하는 것을 이해하고 마스터하는데 도움이 되길 바라며 이 가이드를 작성했습니다.

당신이 기사를 읽고 있다고 가정해봅시다. 이 기사가 무엇을 말하는지 대략적으로 요약하는 서문이 있을 것입니다. 각 단락마다 머릿글이 있을 것입니다. 각 단락은 비슷한 정보들의 그룹으로 구성되어 있을 것이고 기사의 흐름은 매우 읽기 좋을 것입니다.

자 그럼 머릿글이 없는 기사를 생각해 봅시다. 순서도 혼란스럽고 매우 긴 단락이 있습니다. 당신은 기사를 대략적으로 읽을 수 없고 기사의 내용이 무엇을 말하는 지 알기 위해서는 매우 집중해서 읽어야 할 것입니다. 그리고 이것은 꽤 피곤한 일이죠.

당신의 코드도 좋은 기사처럼 되어야 합니다. 당신의 클래스와 파일들의 머릿글을 생각해보시고 메소드를 문단이라고 생각하세요. 당신의 코드 한줄 한줄이 문장입니다. 아래는 좋은 코드의 몇 가지 특성입니다.

1. 깔끔한 코드는 명확하다 - 함수, 클래스, 모듈들은 한가지 일을 원할히 수행한다.
2. 깔끔한 코드는 명쾌하다 - 깔끔한 코드는 읽기 쉬워야 한다. 코드를 읽으면서 당신은 미소가 지어지고 그것이 무슨일을 하는지 정확히 알게 될 것이다.
3. 깔끔한 코드는 정싱이 필요하다 - 코드를 간단하고 정확하게 유지하기 위해서 시간을 들여야 한다.
4. 깔끔한 코드는 테스트를 통과해야 한다 - 동작하지 않는 코드는 깔끔하지 않다.

자 그럼 주니어 개발자로서 좋은 코드를 작성하는 실제적인 방법은 무엇일까요? 아래는 시작하기 위한 저의 팁들입니다.

Use consistent formatting & indentation

책의 줄 간격이 일정하지 않고 폰트 사이즈도 제각각이라면 매우 읽기가 힘들 것입니다. 당신의 코드에서도 마찬가지 입니다. 당신의 코드를 깔끔하고 읽기 좋게 만들기 위해서는 들여쓰기, 줄바꿈, 그리고 규격을 동일하게 하세요. 좋은 예와 나쁜 예를 들어드리죠.

The Good

function getStudents(id) {
     if (id !== null) {
        go_and_get_the_student();
     } else {
        abort_mission();
     }
}

당신은 슬쩍 봐도 if-else 구문이 있다는 것을 알 수 있을 겁니다. 괄호와 들여쓰기가 코드 블록의 시작과 끝을 알기 쉽게 해줍니다. if와 함수 모두 같은 라인에서 중괄호를 연것을 확인할 수 있습니다.

The Bad

function getStudents(id) {
if (id !== null) {
go_and_get_the_student();}
    else
    {
        abort_mission();
    }
    }

들여쓰기가 뒤죽박죽이라서 어디서 함수가 끝나는지 혹은 어디서 if-else 구문이 시작하는지 쉽게 구분할 수 없습니다. 중괄호가 일관적이지 않고 띄워쓰기 또한 들쭉날쭉 하네요. 이것은 조금 과장한 예제이긴 합니다만 일관적인 들여쓰기와 규칙에 대한 장점을 잘 보여줍니다. 좋은 점은 많은 IDE에서는 코드의 규칙을 자동적으로 맞춰주는 많은 플러그인을 지원합니다. 만세!

• VS Code: Prettier
• Atom: Atom Beautify
• Sublime Text: Prettify

Use clear variable and method names

첫 부분에서 코드를 읽기 쉽게하는 것이 얼마나 중요한지 말씀드렸습니다. 이 측면에서 가장 중요한 것은 작명입니다. 좋은 작명의 예를 보도록 하죠

function changeStudentLabelText(studentId){                  
     const studentNameLabel = getStudentName(studentId);
}
function getStudentName(studentId){
     const student = api.getStudentById(studentId);
     return student.name;
}

이 코드는 여러가지 좋은 점이 있습니다.

• 함수와 매개변수의 이름이 명확합니다. 개발자가 이것을 읽는 즉시 학생번호를 넘기면 학생이름을 받을 수 있겠구나 라는 것을 알게됩니다. 그들은 그 메소드의 내부를 살펴볼 필요도 없습니다.
• getStudentName의 메소드와 변수들 또한 매우 적절히 작명되었습니다. api를 부르면 student 객체를 전달받고 name 특성을 리턴합니다. 참 쉽죠?

신입개발자들에겐 깔끔한 코드를 작성할 때 좋은 작명을 하는 것이 생각보다 힘들겁니다. 당신의 프로그램이 커져도 읽기 쉽게 하기 위해서 이 규약들을 사용하세요.

• 작명 스타일의 일관성을 유지하세요, 카멜케이스를 쓰거나 언더바 둘 중 하나만 쓰세요.
• 함수, 메소드, 변수의 이름은 그들이 무엇을 하는지, 무엇인지 나타내는 것으로 작명하세요. 만약 당신의 메소드가 무언가를 가져오는 것이라면 get을 붙이세요. 만약 당신의 변수가 차의 색깔을 저장하는 것이라면 carColor 이라고 지으세요.

Bonus Tip - 만약 당신이 함수나 메소드에 이름을 지을 수 없다면 그것은 그 함수가 너무 많은 일을 하는 것입니다. 함수를 쪼갤 수 있도록 해보세요. 에를 들면 updateCarAndSave() 대신에 updateCar()와 saveCar()로 나누는 거죠.

Use comments where necessary

이것은 주석이 없어도 충분히 잘 읽히는 코드를 작성하라는 것입니다. 물론 이것은 완벽한 세상에서나 말이 되죠. 아직 코딩의 세상은 완벽가 거리가 멀기 때문에 때때로 주석이 필요합니다.

문서의 주석은 특정 함수나 클래스가 어떤 것인지 설명해줍니다. 당신이 라이브러리를 작성하고 있다면 이것은 당신의 라이브러리를 사용하는 사람에게 도움이 될 것입니다. useJSDoc의 예제를 보여드리겠습니다.

/** * Solves equations of the form a * x = b
* @example *
// returns 2 * globalNS.method1(5, 10);
* @example *
// returns 3 * globalNS.method(5, 15);
* @returns {Number} Returns the value of x for the equation. */ globalNS.method1 = function (a, b) { return b / a; };

#피해야 할 주석의 예
#Redundant comments that don't add value
// this sets the students age
function setStudentAge();

#Misleading comments
//this sets the fullname of the student
function setLastName();

#Funny or insulting comments
// this method is 5000 lines long but it's impossible to refactor so don't try
function reallyLongFunction();

Remember the DRY principle(Don’t Repeat Yourself)

Dry 원칙이 말하는 것은 이것입니다:

모든 지식은 시스템 내에서 하나의 모호하지 않고 권위있는 표현을 가져야 한다. 쉽게 얘기해서 이미 존재하는 코드를 복제하는 것을 최대한 줄이라는 것입니다.(줄이는 것이지 모두 제거하라는 말이 아닙니다. 코드에 중복되는 변수가 좀 있어도 세상이 멸망하진 않습니다.)

Don’t “over clean” your code

저는 가끔 개발자들이 지나치게 깔끔한 코드를 작성하려고 하는 것을 봤습니다. 코드를 너무 깔끔하게 작성하려고 하지 마세요, 그것이 지나치면 오히려 읽기 어렵고 유지보수 하기 어렵게 된답니다. 그리고 생산성에 영향을 줄 수도 있습니다. 클린 코드에 대한 태도를 갖되 당신의 프로젝트 초반에 너무 많이 생각하지 마세요. 대신에 코드가 정확히 동작하는지 확인하고 테스트 하세요. 리펙토링을 하는 단계가 당신이 DRY 원칙이나 다른 것들을 활용해 클린 코드를 생각해야 할 때 입니다.

Summary

• 좋은 코드를 작성하는 것은 좋은 기사를 쓰는 것과 유사하다.
• 들여쓰기, 중괄호 위치 등 외관적인 것에서 부터 작명까지 세세한 부분을 신경써야 한다.
• 프로젝트 초반에는 함수의 동작과 테스트에 중점을 두고 리팩토링 단계에서 클린 코드에 대해 생각하자
• 신입 개발자에게 클린 코드를 작성하려는 태도를 갖는 것은 매우 중요하다!