코드 주석에 제목을 작성합니까? [닫은]

나는 내가 쓴 오래된 코드 (대학에서 첫해)를 탐색하고 있었고 코드의 다양한 부분보다 먼저 주석 제목을 쓰는 것을 보았습니다. 같은 것 (이것은 독점 게임에서 온 것입니다) :

/*Board initialization*/
...code...

/*Player initialization*/
...code...

/*Game logic starts here*/
/*Displaying current situation*/
...code...

/*Executing move*/
...code...

/*Handle special event*/
...code...

/*Commit changes, switch to next player*/
...code...

코드가 정말 명확하면 중복 될 수 있으며 불필요하게 불필요하지만 파일을 스캔 한 결과 실제 코드를 거의 보지 않아도 무슨 일이 일어나고 있는지 알고있는 것처럼 느껴졌습니다. 나는 이것이 특정 상황에 맞는 것으로 분명히 볼 수 있으므로, 당신은 이것을 궁금합니다. 좋은 생각이라고 생각하십니까? 아니면 너무 많은가?

이것은 코드 냄새입니다. 이것이 무엇이고 왜 그렇지 않은지 말해 줍니다.

이것이 필요한 경우 코드를 작은 기능으로 분할하십시오.

나는 항상 그렇게한다. 둘 다 코드가 무엇을하고 있는지를 표시하고, 더 중요한 것은 아마도 코드를 쉽게 스캔하고 찾을 수 있도록하는 것입니다. 때로는 주석에 관련된 프로세스를 작성하고 주석에 따라 코드를 '채울 수 있습니다'.

나는 왜 많은 사람들이 실제로 그 이유를 설명하지 못하고 연습을 싫어하는지 흥미 롭습니다. 그와 같은 의견이 눈살을 찌푸리는 이유는 당신이 단일 책임 원칙을 위반 한 표시이기 때문입니다. 특정 이름은 일반적으로 OO 컨텍스트에서만 사용되지만 일반적인 개념은 응집력이라고도하며 다른 패러다임에도 적용됩니다. 학교는 보통 학위 프로그램이 끝날 때까지 이런 종류의 디자인 원칙을 가르치지 않습니다. 실제로 일부 교사는 모든 것을 하나의 파일로 작성하여 채점하기가 더 쉬워 지도록 위반을 명령합니다. 따라서 신입생 무지는 변명 할 수 없으며 상황에 따라 "무언가"가 잘못되고 의견으로 명확하게 설명하려고 시도한 사실은 칭찬받을 만하지 만 일반적으로 의견으로 논문을 작성하는 것보다 불명확 한 디자인을 수정하는 것이 좋습니다.

코드를 더 명확하게 만들거나하지 않는 방법으로 이러한 것을 봅니다. 당신은 각 부분이 무엇인지 파일의 방법을 기반으로 말할 수 있다면 당신은 그러나 경우 필요가 없다 가 그 때 유용 할 수 있습니다 여러 섹션을 가지고는. 코드 파일이 너무 커지면 해당 주석의 필요성을 줄일 수있는 분류해야합니다.

나는 팀 내에서 표준을 생각해 내기 위해 적어도 같은 방식으로 코딩하고 주석을 달아 코드를 쉽게 볼 수 있다고 말합니다.

나는 종종 나 자신에게 의도를 전달하거나 본질적으로 "데이터 정리가 여기서 시작됩니다"와 같은 편리한 책갈피를 작성하기 때문에이 작업을 수행합니다. 일반적으로 그 제목 아래에 내가하고있는 일과 그 이유에 대한 간단한 내용이 있습니다.

나는 중복성을 좋아한다. 어떤 이유로 든 랩 노트를 잃어 버리거나 몇 년 전에 작성한 코드를 다시 방문해야하는 경우, 내가하고있는 작업과 수행 한 이유를 함께 모으는 것을 싫어합니다. 해당 논리 중 적어도 일부가 코드에 있으면 최소한 다시 작업 할 수있을만큼 충분히 문서화되어 있습니다.

나는 그것에 대한 내 성향의 일부가 상당히 많은 양의 프로그래밍이 본질적으로 통계적이므로 다소 반복적이라고 생각합니다. 검색 할 유용한 이름의 함수가있는 코드가 몇 개있을 수 있지만, 일반적인 선형 모델 함수와 비슷한 비슷한 수십 가지 용도가있을 수 있습니다. "선택 A와 선택 B 또는 C에 대한 결과가 얼마나 민감한 지"코드 중 어느 것이 다른 코드인지 찾아 보는 것이 유용합니다. 그것은 종종 제목에 의해 속도가 빨라집니다.

수십 가지 기능을 가진 거대한 소스 파일이 있고 그 덩어리를 느슨하게 구성 할 수있는 상황에서 유용하다고 생각합니다. 그러나 작고 집중된 소스 파일보다 낫다는 말은 아닙니다.