커피 브레이크 #79. Java 개발자의 성공을 가로막는 10가지 실수 의미 있는 코드 주석 작성을 위한 개발자 가이드

Java 개발자의 성공을 방해하는 10가지 실수

출처: Dev.to 내 경험을 바탕으로 개발자가 성공을 방해하는 10가지 실수 목록을 작성했습니다.

1. 단위 테스트를 작성하지 마세요

단위 테스트를 작성하지 않는 개발자는 코드에서 더 많은 실수를 저지릅니다. 이는 제품 불안정과 고객 불만으로 이어집니다.

2. 코드를 수동으로 확인하지 않습니다

단위 테스트로 코드를 완전히 커버하더라도 여전히 뭔가를 놓칠 가능성이 있습니다. 검토를 위해 코드를 제출하기 전에 항상 수동으로 테스트하는 것이 좋습니다. 이렇게 하면 개발 단계에서 오류를 감지할 수 있습니다.

3. 그들은 “이런 일은 절대 일어나지 않을 거야”라고 생각합니다.

개발자는 새로운 코드를 작성할 때 특정 시나리오가 절대 발생하지 않을 것이라고 생각하여 실수를 저지르는 경우가 많습니다. 결국 그들은 틀렸다는 것이 밝혀졌습니다. 코드가 실행될 수 있는 모든 시나리오를 처리합니다. 방어적인 프로그래밍 방법이 이에 도움이 될 것입니다.

4. 피드백을 받지 마세요

다른 개발자와 사용자로부터 정기적으로 피드백을 요청하세요. 동료들과 의견을 공유하십시오.

5. 코드의 기능을 확인하지 않습니다.

개발자는 코드를 작성하지만 기능을 확인하지 않는 경우가 많습니다. 결과적으로 코드가 프로덕션에 도달하면 다양한 문제가 발생합니다.

6. 긴 절차 코드 작성

많은 논리를 사용하여 긴 메소드를 작성하는 것은 매우 쉽습니다. 이를 통해 프로그래머는 여러 위치에서 동일한 논리를 구현합니다. 상당수의 작은 메서드가 포함된 프로젝트는 코드 재사용이 훨씬 더 좋고 유지 관리도 훨씬 쉽습니다.

7. 도구를 모른다

도구는 손의 연장입니다. 당신이 그들을 더 잘 알수록, 당신의 생산성은 더욱 높아질 것입니다. 사용 중인 IDE에 대해 잘 알고 있어야 합니다. 빠른 명령을 배우십시오. 생산성을 높이는 데 도움이 되는 명령이 항상 있습니다. IntelliJ IDEA에서는 Sonar Lint, Spot bug 및 Code Metrics가 있습니다.

8. 코드의 문제를 무시하세요

가장 성공적인 제품을 개발하는 개발자는 끊임없이 코드를 변경합니다. 코드를 리팩터링하는 것을 두려워하지 마세요. 코드가 단위 테스트된 경우 회귀 가능성이 거의 없습니다. 개발자는 문제가 있는 코드를 무시하는 경우가 많습니다. 개발자로서 귀하는 애플리케이션을 양호한 상태로 유지 관리할 책임이 있습니다. 이러한 이유로 발견된 문제를 해결하십시오.

9. 결과를 깨닫지 못한 채 코딩합니다.

개발자는 결과를 이해하지 못한 채 코드를 변경하여 프로덕션에 출시해서는 안 됩니다. 코드는 주어진 테스트 값에 대해 올바른 결과를 생성할 수 있습니다. 그러나 이로 인해 예측할 수 없는 결과가 발생하고 심각한 문제가 발생할 수 있는 시나리오가 있을 수 있습니다. 개발자가 완전히 이해하지 못하는 라이브러리의 기능을 사용할 때 "예측할 수 없는" 코딩이 자주 발생합니다. 이는 개발자가 솔루션을 이해하지 못한 채 문제를 해결할 때도 발생할 수 있습니다.

10. 도움을 요청하지 마세요

개발자는 별로 사교적인 사람이 아닙니다. 그들은 스스로 문제를 해결하는 것을 좋아합니다. 하지만 개발자 한 명이 처음부터 끝까지 제품을 직접 만드는 시대는 끝났습니다. 소프트웨어 개발은 ​​팀 활동입니다. 프로그래밍하는 동안 문제가 발생하면 스스로 해결하려고 노력하십시오. 하지만 해결책을 찾을 수 없다면 너무 많은 시간을 낭비하지 마세요. 동료 중 일부는 이미 동일한 문제에 직면하여 해결책을 알고 있을 가능성이 높습니다. 이렇게 하면 시간이 절약되고 생산성이 향상됩니다.

의미 있는 코드 주석 작성을 위한 개발자 가이드

출처: Stepsize 대부분의 경우 동일한 프로젝트나 코드베이스에서 작업하는 사람은 당신뿐만이 아닙니다. 이는 다른 사람들이 귀하의 코드를 이해해야 함을 의미합니다. 이는 코드 주석에도 해당됩니다. 개발자들은 맥락 없이 "빠르고 지저분한" 댓글을 작성하는 경우가 많아 동료들이 작성자가 말하려는 내용을 혼란스럽게 만듭니다. 이는 나쁜 습관이며 명확성보다 더 많은 혼란을 야기합니다. 명확한 코드 주석을 작성하면 다른 개발자에게 도움이 됩니다. 함수, 함수의 이론적 근거, 입력 및 출력을 설명하는 코드 주석은 다른 개발자의 학습 프로세스를 가속화합니다. 반면에 코드 주석은 다음과 같은 질문으로 이어집니다. 코드 주석을 작성할 가치가 있습니까? 상당수의 개발자 그룹이 코드 주석 작성에 반대합니다. 그 이유는 코드가 자명하다고 생각하기 때문입니다. 다른 개발자가 코드를 보고 코드의 목적을 이해할 수 없다면 이는 잘못된 코드입니다. 아마도 이것이 사실일 것이다. 그러나 코드를 주석 처리하는 데 필요한 약간의 노력과 코드가 가져올 잠재적 이점에 대해 생각해 보십시오. 코드 주석은 모든 개발자, 특히 후배의 온보딩 프로세스 속도를 높이는 데 중요합니다. 다양한 유형의 코드 주석을 살펴보겠습니다.

1. 문서에 대한 의견.

이러한 주석의 주요 목적은 파일이나 구성 요소의 목적을 신속하게 명확하게 하는 것입니다. 구성 요소의 기능을 이해하기 위해 구성 요소의 전체 코드를 읽는 대신 '인덱스' 파일 상단에 코드 설명을 추가할 수 있습니다. 이는 이 구성 요소의 기능을 설명하는 데 도움이 됩니다. 나는 이런 유형의 주석을 별로 좋아하지 않습니다. 왜냐하면 코드가 약간 복잡해지기 때문입니다. 저는 이러한 유형의 아키텍처 주석이 프로젝트 아키텍처를 중앙에서 유지 관리하고 논의할 수 있는 내부 문서에 있어야 한다고 생각합니다. 그러나 오픈 소스 프로젝트에는 실제로 이러한 기능이 필요합니다.

2. 기능에 대한 설명.

이것은 가장 유용한 유형의 주석입니다. 이는 함수의 목적, 매개변수 및 출력을 설명합니다.

/**
 * @desc Creates a welcome message
 */
function sayHello(name) {
    return `Hello ${name}`;
}

3. 논리적인 의견.

이는 복잡한 코드 경로를 명확히 하기 위한 함수 내의 주석입니다. 짐작할 수 있듯이 이러한 주석이 있다는 것은 코드가 너무 복잡하다는 것을 나타냅니다. 또한 논리적인 의견에는 너무 많은 세부 정보가 포함되어 있는 경우가 많습니다. 세부 수준은 더 많은 혼란을 야기하고 코드의 가독성을 감소시킵니다. 다음은 지나치게 상세한 코드 주석의 예입니다.

let date = new Date(); // store today's date to calculate the elapsed time

코드 주석 달기: 주석 달기를 위한 4가지 모범 사례

1. 코드 주석 또는 태그 사용

많은 프로그래밍 언어는 코드 주석 처리에 대한 표준을 정의합니다. Java는 Javadoc을 사용하는 반면 JavaScript는 많은 문서 도구에서 지원되는 JSDoc 코드 주석 시스템을 사용합니다 . 함수의 경우 다음 코드 태그를 포함해야 합니다.

• @desc - 함수 설명
• @param - 함수가 허용하는 모든 입력 매개변수입니다. 입력 유형을 지정해야 합니다.
• @returns - 반환된 출력입니다. 출력 유형을 지정하십시오.
• @throws는 함수가 던질 수 있는 오류 유형입니다.
• @example - 입력과 예상 출력을 보여주는 하나 이상의 예입니다.

다음은 청크 함수 에 대한 Lodash 코드 의 예입니다 .

/**
 * Creates an array of elements split into groups the length of `size`.
 * If `array` can't be split evenly, the final chunk will be the remaining
 * elements.
 *
 * @since 3.0.0
 * @category Array
 * @param {Array} array The array to process.
 * @param {number} [size=1] The length of each chunk
 * @returns {Array} Returns the new array of chunks.
 * @example
 *
 * chunk(['a', 'b', 'c', 'd'], 2)
 * // => [['a', 'b'], ['c', 'd']]
 *
 * chunk(['a', 'b', 'c', 'd'], 3)
 * // => [['a', 'b', 'c'], ['d']]
 */
function chunk(array, size = 1) {
  // logic
}

2. 귀하의 행동에 대한 이유를 설명하십시오

많은 개발자는 주석을 사용하여 코드의 기능을 설명합니다. 그렇게 할 때 특정 기능이나 구성 요소를 만든 이유를 포함해야 합니다. 이 정보를 컨텍스트라고 합니다. 개발자에게 기능이나 구성 요소 뒤에 있는 설계 결정에 대한 추가 정보를 제공하려면 컨텍스트가 중요합니다. 다른 개발자가 기능이나 구성 요소를 변경하려는 경우 컨텍스트가 중요합니다. 아래에서는 문맥 없이 코드에 주석을 다는 나쁜 예를 볼 수 있습니다.

/**
 * Sets the label property of a new form.
 *
 * @param label text for label of form
 */
function setFormLabel(label) {
    // logic
}

3. 다른 문서나 댓글에 링크를 걸지 마세요

기능이나 구성 요소를 설명하는 다른 코드 주석이나 내부 문서에 연결하는 것은 권장되지 않습니다.

/**
 * Sets the label property of a new form.
 *
 * @see {@link https://myinternaldocument.com}
 */
function setFormLabel(label) {
    // logic
}

4. 코딩하면서 댓글 쓰기

이는 당연한 것처럼 보일 수 있지만 많은 개발자(나 자신 포함)는 이 규칙을 무시합니다. 나중을 위해 주석을 남기는 것은 작성한 논리 중 일부를 잊어버릴 수 있고 이로 인해 코드 주석의 품질이 낮아질 수 있기 때문에 좋지 않습니다. 며칠 동안 동일한 풀 요청을 작업한 경우 특히 그렇습니다. 기능이나 모듈을 막 마친 후에 댓글을 작성하는 것이 좋습니다. 코드 주석을 가능한 한 짧게 유지하는 것을 잊지 마세요. 코드 자체를 작성하는 것보다 주석을 작성하는 데 더 많은 시간을 소비할 필요가 없습니다.