문서 스타일

Question

프로그래밍 클래스 중 하나 인 강의 요약에서 "코드를 보지 않고 주석 만 읽고 코드를 수행하는 것이 가능하면 문서로 충분합니다."

이와 같은 문서 스타일에 대해 들어 보셨습니까? 좋은 습관입니까? 극도로 열정적 인 것 같습니다.

Answer 1

코드를 따라야합니다. 이것은 여러 가지 방법으로 달성 될 수있다 :

1. 적합하고, 특히 어려운 알고리즘이나 복잡한 코드

적절한 문서가 사용하는 모든 코드의

광범위한 문서에 주석

명명 의미 세 가지 접근 방식 모두 적절하다.

그러나 코드의 잠재 고객이 주로 코드를 이해하고 개념에 대한 이해를 평가하려고 할 때, 즉 학술적 맥락에서 세 번째 코드가 매우 바람직 할 수 있습니다.

생산 시스템에 문제가있어 아침 3시에 콜 아웃 중이면 최악의 비방자가 이해할 수 있도록 모든 코드를 작성하고 문서화해야합니다.

동시에 과도한 주석은 유지 관리해야 할 또 다른 항목이며 코드가 변경되면 코드와 동기화되고 주석은 변경 사항 중 적절히 유지 관리 될 항목이 가장 적습니다.

Answer 2

나는 내 자신의 under-grad 작업에 처음에는 이와 같은 요구 사항이있었습니다. 지나치게 과장 할 수도 있지만, 사람들이 코드에 대해 논평을하면, 나는 그것을위한 것입니다.

Answer 3

나는 그 반대 다. 훌륭한 문서는 스스로를 표현하는 코드입니다! 일부 의견은 코드를 읽기 쉽고 즐겁게 만드는 경향이 있습니다. 우리가 이것을 초보자들에게 계속해서 말하면, 코드 비율이 매우 낮을 프로그램을 작성하게 될 큰 위험이 있습니다 (다른 말로하면, 코드가 좋지 않은 코드를 주석으로 처리했다는 것을 의미합니다) . 의견은 사소한 알고리즘이나 지침을 설명 할 때만 작성해야합니다. 나머지는 코드에 남겨 두어야합니다 (예 : 자신의 직업을 이해하는 것과 같은 변수의 이름 지정).

Answer 4

좋은 습관입니다. 이는 코드를 블랙 박스로 취급 할 수 있다는 것을 의미합니다. 나는 이렇게 문서화하는 것이 재미 있지 않다는 데 동의하지만 동료가 도와 줄 것을 고려할 수도 있습니다. 테크니컬 라이터와 같은 전문가일지도 모릅니다.

Answer 5

클래스 컨텍스트에서 예. 그 교수는 코드 뒤에 당신의 의도를 알고 싶어합니다. 그 교수는 당신의 코드를 보는 것을 제외하고는 이것을 물어볼 수있는 쉬운 방법이 없습니다. 또한 작은 프로그램 가능 청크로 할당 부분을 분리하는 데 도움이됩니다.

현실 세계에서? 그것은 달려있다. 우리는 커밋하는 동안 수정하는 클래스에 작업을 기록합니다. 변경 사항의 의도를 문서화하는 것이 좋습니다. 많은 의견은 많은 유지 보수가 필요합니다. 주석이 구현 이유를 설명하고 해당 구현이 변경되면 해당 주석도 더 잘 변경됩니다.

Answer 6

지시가 모호합니다. 강사로부터 명확한 설명을 찾아야합니다.

일부 사람들은 그 명령이 귀하의 의견이 코드를 설명한다는 것을 의미 할 수도 있습니다. 그것은 대학 후에 좋은 연습이 아닙니다. 그러나 이것은 경험에서 비롯된 것입니다. 초보자 용 작업에 이르기까지 매우 도움이 될 수 있습니다. 당신은 당신의 일을 채점하는 사람들에게 도움이되고 싶습니다.

대체 방법으로는 코드의 일부, 즉 클래스, 메소드, 코드 블록을 더 작은 메소드로 더 잘 리팩터링 할 수있는 긴 메소드로 문서화해야합니다. 이 중 일부의 예제는 많은 클래스 라이브러리에서 생성 된 API 문서에서 찾을 수 있습니다.