의견 작성 초보자 가이드?

27

신진 개발자를 겨냥한 코드 주석 작성에 대한 명확한 안내서가 있습니까?

이상적으로는 주석을 사용해야 할 때와 사용하지 않아야 할 시점 및 어떤 주석을 포함해야하는지 설명합니다.

이 답변 :

현재하고있는 일에 대해서는 언급하지 말고 왜해야합니까?

WHAT는 변수 이름을 적절히 선택하여 깔끔하고 읽기 쉽고 간단한 코드로 처리합니다. 주석은 코드 자체로는 보여줄 수없는 (또는 어려운) 코드의 상위 구조를 보여줍니다.

친숙한 프로그래머에게는 약간 간결합니다 (여러 예제와 코너가있는 확장은 훌륭 할 것입니다).

업데이트 : 여기에 대한 답변 외에도 다른 질문에 대한 이 답변 이 관련성 이 있다고 생각 합니다 .

language-agnostic  comments 
— 카메론
소스
사람들이 더 이상 언급하지 않는 세상으로 빠르게 이동하고 있다고 생각합니다. 더 나아질수록 더 나아질 것입니다. 기민한.
— MK01
1
@ MK : 그 경우 ( 이 답변에 더 동의하는 경향이 있다면 ) 의견을 쓰지 않는 방법 과 피해야하는 이유를 설명하는 가이드 가 유용합니다. 사실 다른 관점이 많을수록 좋습니다.
— Cameron
나는 작은 주석이 코드 읽기 속도를 높이는 데 도움이되며 항상 도움이 될 것이라고 생각합니다. 나는 "단순한 의견"추론을 완전히 구입하지는 않습니다. 비록 그들이 오래되었지만 역사적인 가치가있을 것입니다. 나는 때때로 여기와 거기에 자세한 주석이있는 코드베이스에서 작업했으며 주석이 오래된 문제로 실제로 물린 적이 없었습니다.
— MK01
— 모기

답변:

38

주석의 가장 큰 약점을 알고 있어야합니다. 즉, 코드가 변경 될 때 개발자는 코드와 동기화 상태를 유지하기 위해 주석을 거의 업데이트하지 않습니다. 즉, 절대 신뢰할 수 없으며 코드를 읽을 수 있습니다. 이런 이유로 코드는 자체 문서화되어야합니다. 코드가 산문처럼 읽히도록 함수와 변수 이름을 선택해야합니다.

코드가 무엇을하고 있는지 문서화하지 마십시오. 자체 문서화 코드가이를 처리해야합니다. 왜하고 있는지 문서화하십시오. WHY는 일반적으로 비즈니스 규칙 관련 또는 아키텍처 관련이며 WHAT에서 자주 변경되지 않으며 부실합니다. 문서 엣지 케이스. 문서 예외. 문서 디자인 결정. 그리고 가장 중요한 것은 당신이 고려한 설계 결정을 문서화하지만 구현하지 않기로 결정한 것입니다 (그리고 사용하지 않기로 결정한 이유를 문서화하십시오).

2
마지막 것은 매우 중요합니다. 때로는 명백한 솔루션을 구현하는 데 버그 / 부작용이 있습니다. 다른 솔루션과 함께 사용하기로 선택한 이유를 문서화하면 다음 개발자가 엉뚱한 솔루션을 "수정"할 때 다음 개발자가 버그를 다시 소개하지 못합니다.
— CaffGeek
2
또 다른 요점은 첫 번째 직업은 주석을 코드만큼 중요하다고 생각했습니다. 검토 할 때 코드뿐만 아니라 주석을 읽는 습관을 가지도록하고 가능할 때마다 주석을 최신 상태로 유지하십시오. 이를 통해 주석이 부실 해지는 것을 방지하고 코드에 문서화 된 비즈니스 규칙 등을 최신 상태로 유지할 수 있습니다.
— Eric Hydrick
10

Robert C. Martin의 Clean Code 책을 읽어야합니다 . . 주석이 필요한 경우 제대로 코딩하지 않았을 가능성이 높습니다. 이상적으로 코드는 "자체 주석"이어야합니다. Clean Coder 책은이를 수행하는 방법을 설명하므로 주석이 필요하지 않으며 필요한 상황에서 주석을 작성하는 방법을 잘 설명했습니다. (복잡한 수학 공식을 설명하는 것처럼)

— 단발
소스
나는 너무 많은 복잡한 수학 공식이 원하지 않을 것이지만 설명 내가 원하는 것으로 기입 의 의미와 소스에 대한 설명과 함께, 적절한 수학적 표기법 (아마도 텍)에서. 공식을 이해하지 못하면 어쨌든 값을 계산하는 데 사용하는 코드를 엉망으로 만들면 안됩니다.
— CVn
코드는 말할 수있는 방법 이 아닌 이유 또는 이유가 없습니다 . 이에 대한 의견이 필요합니다.
7

언급 한 바와 같이 Code Complete에는 주석 작성에 대한 다양한 지침이 있습니다. 간단히 말해 PDL이며 다음과 같이 요약 할 수 있습니다.

  1. 코드가하는 일이 아니라 의도를 설명하십시오. 몇 가지 트릭을 사용하거나 사용자 지정 구현을 사용하지 않는 한 구현 세부 사항을 설명하지 마십시오. 예를 들어, 시프트 비트를 사용하여 나누거나, 포인터 산술을 사용하여 클래스 멤버에 액세스하거나 일부 풀링 된 객체에 대해 사용자 지정 메모리 할당자를 사용합니다.

  2. 의사 코드 (예 : 주석)를 먼저 작성한 다음 루틴 / 방법 / 함수 설명을 마친 후에 실제 코드로 작성하십시오. 사용되는 언어는 수준이 높지만 구체적이므로 다소 장황 할 수 있습니다.

  3. 코드를 작성하기 전에 코드가 무엇을하고 있는지 이해하십시오

  4. 실제 코드와 유사한 주석을 작성하십시오

목표는 구식 일 수있는 오래 걸리지 않은 관련없는 주석은 피하지만 코드의 의도와 목적을 반영하는 주석을 갖는 것입니다. 높은 수준의 의사 코드를 사용하면 구현을 작성하기 전에 생각을 명확히하는 데 도움이됩니다.

책을 추적하고 싶지 않은 경우를 대비하여 GameDev.net [PDL 설명] [1]에 링크가 있습니다.

— 엑스트라 쿤
소스
5
의사 코드 (즉, 주석)를 먼저 작성하십시오 . 더 이상 동의하지 않았습니다. 주석이 코드와 일치하지 않도록하는 더 좋은 방법은 없습니다. 새로운 코더 (및 초보자 가이드를 위해 특별히 요구 한 사람)는 기뻐하기 전에 기능을 100 번 해킹하고 리팩터링하며, 코드는 빠르게 이동하고, 재 작성되고, 용도 변경되며, 결국에는 우아한 작업 솔루션을 가지고 있지만 초기 의사 코드처럼 보이지 않습니다. 코드가 작동함에 따라 주석이 이동 및 업데이트됩니까? 당신은 그들이하지 않을 달콤한 bippy 내기 할 수 있습니다. 내 두 센트
— 이진 걱정
1
또한 의사 코드 주석은 코드의 기능을 알려줍니다. 코드에서 알려줄 것입니다. 의사 코드는 코드가 왜 그런지 알려주지 않습니다. -1 친구, 미안하지만 두 번째 요점에 동의 할 수 없으며 시간이 변경되었습니다.
— 이진 걱정
1
의사 코드는 논란의 여지가 없지만 더 많은 설명이 필요합니다. 의사 코드는 작성한 코드의 의도를 설명하는 것입니다. 즉, 주석은 구현 세부 정보 (예 : "스택 상단에 x 추가")가 아니라 코드가 수행해야하는 작업 (예 : "창을 다른 모든 항목 앞에 표시")에 대한 것입니다. 올바르게 지적했듯이 코드로 주석을 이동해야합니다. 코드에 동의하지 않으면 코드가 무엇을하고 있는지 항상 알 수 있습니다. 도움이 될 수도 있고 정확한 의견이 있다면 (잘 작성하면!) 결국, 여전히 IMHO.
— 엑스트라 쿤
3
호출 된 메소드 또는 함수 showWindowOnTop(window)는 항상 동일한 특성에 대한 주석보다 낫습니다.이 모든 것은 2012 년에 구식이며 나쁜 조언입니다. 1) 함수 / 메소드 이름은 의도를 설명합니다. 2) 의사 코드는 최신 툴 체인을 사용한 속이 빈 운동입니다. 3) 테스트는 코드를 작성하기 전에 코드가 수행해야 할 작업을 알려줍니다. 4) 잘 이름이 지정된 코드는 이름이 잘못 지정된 코드와 일치하지 않는 주석보다 낫습니다
1

내 제안은 어떤 주석도없이 코드를 작성한 다음 코드에서 벗어나는 것입니다. 1 년 후에 다시 와서 읽어보십시오. 쉽게 이해하지 못하는 부분은 주석을 달아야 할 부분입니다.

— 케빈
소스
1
Hah, yes ;-) 이것은 특히 도움이되지 않는 조언입니다. 아마도 이것은 주석이었을 것입니까?
— Cameron
당신이 이해하지 못하는 부분은 더 작고 더 나은 이름의 부분으로 작성해야합니다. 주석이 코드에 포함되는 주된 이유는 함수 / 메서드가 길어지고 더 작은 자체 문서화 조각이어야한다는 것입니다.
0

에반 토드 (Evan Todd)가 유일하게 유용한 댓글 카테고리 ( 블로그에서 인용) 에 대한 자신의 견해를 요약 한 방식이 정말 마음에 듭니다 .

  • 무엇보다 이유를 설명하는 의견. 이것들이 가장 유용합니다.
  • 다음의 거대한 코드 덩어리가하는 일을 설명하는 몇 마디의 주석. 탐색 및 읽기에 유용합니다.
  • 각 필드의 의미를 설명하는 데이터 구조 선언의 주석. 이것들은 종종 불필요하지만 때로는 개념을 메모리에 직관적으로 매핑 할 수 없으며 매핑을 설명하기 위해 주석이 필요합니다.
— 카메론
소스
당사 사이트를 사용함과 동시에 당사의 쿠키 정책과 개인정보 보호정책을 읽고 이해하였음을 인정하는 것으로 간주합니다.
Licensed under cc by-sa 3.0 with attribution required.