표준 문서

Question

나는 연간 10~15개의 프로젝트를 담당하는 약 15명의 개발자로 구성된 팀을 위한 코딩 표준 문서를 작성하고 있습니다.다른 섹션(찾는 대로 여기에 게시할 수 있음) 중에서 코드 형식 지정에 대한 섹션을 작성하고 있습니다.따라서 우선 어떤 이유로든 기본적이고 일관된 코드 형식 지정/이름 지정 표준을 설정하는 것이 현명하다고 생각합니다.

저는 이 팀이 지난 3년 동안 작성한 대략 10개의 프로젝트를 살펴보았는데 확실히 꽤 다양한 스타일을 발견했습니다.계약자는 때때로 들어오고 나가고 때로는 팀 규모를 두 배로 늘리기도 합니다.

저는 정말 효과가 있었던 코드 형식 지정 및 명명 표준에 대한 몇 가지 제안을 찾고 있습니다.하지만 그것도 실제로 정당화될 수 있습니다.일관성과 공유 패턴이 코드를 더 유지 관리하기 쉽게 만드는 데 큰 도움이 된다고 생각합니다.하지만 상기 표준을 정의할 때 고려해야 할 다른 사항이 있습니까?

• 괄호는 어떻게 라인업하나요?클래스, 메소드, Try catch 블록, 스위치 문, if else 블록 등을 다룰 때 동일한 괄호 지침을 따르십니까?

• 열에 필드를 정렬합니까?개인 변수에 밑줄을 표시하거나 접두사를 붙이나요?파일에서 특정 항목을 더 쉽게 찾을 수 있도록 명명 규칙을 따르나요?학급 구성원의 순서는 어떻게 정하나요?

네임스페이스, 패키징 또는 소스 코드 폴더/조직 표준에 대한 제안은 어떻습니까?나는 다음과 같은 것부터 시작하는 경향이 있습니다.

<com|org|...>.<company>.<app>.<layer>.<function>.ClassName

나는 이러한 표준을 지시하기 전에 내가 익숙했던 것보다 더 많이 받아들여지는 다른 관행이 있는지 궁금합니다.이미 온라인에 게시된 표준에 대한 링크도 훌륭할 것입니다. 이미 일부 작업을 수행했지만 말입니다.

Answer 1

먼저 귀하의 언어에 맞는 자동 코드 포맷터를 찾으십시오.이유:문서에 무엇이라고 쓰여 있든 사람들은 필연적으로 규칙을 어길 것입니다.코드 검토에서 세부 사항을 선택하는 것보다 포맷터를 통해 코드를 실행하는 것이 훨씬 쉽습니다.

기존 표준이 있는 언어를 사용하는 경우(예:Java, C#)을 사용하는 것이 가장 쉽습니다. 아니면 최소한 첫 번째 초안으로 시작하는 것이 가장 쉽습니다.Sun은 형식 지정 규칙에 대해 많은 생각을 했습니다.당신은 그것을 활용할 수도 있습니다.

어쨌든 많은 연구 결과에 따르면 중괄호 위치 및 공백 사용과 같은 다양한 사항이 생산성이나 이해 가능성 또는 버그 확산에 측정 가능한 영향을 미치지 않는다는 사실을 기억하십시오.그냥 갖는 것 어느 표준이 핵심이다.

Answer 2

자동차 산업에서 구체적인 이유로 사용되는 몇 가지 스타일 표준은 다음과 같습니다.

제어 구조에서는 항상 중괄호를 사용하고 별도의 줄에 배치합니다.이렇게 하면 사람들이 코드를 추가하고 이를 제어 구조 내에 실수로 포함하거나 포함하지 않는 문제가 제거됩니다.

if(...)
{

}

모든 스위치/선택에는 기본 케이스가 있습니다.기본 사례에서는 유효한 경로가 아닌 경우 오류를 기록합니다.

위와 같은 이유로, any if...elseif...제어 구조는 유효한 경로가 아닌 경우 오류를 기록하는 기본값 else로 끝나야 합니다.단일 if 문에는 이것이 필요하지 않습니다.

루프 또는 제어 구조가 의도적으로 비어 있는 경우에는 이것이 의도적임을 나타내기 위해 항상 세미콜론이 배치됩니다.

while(stillwaiting())
{
   ;
}

명명 표준에는 typedef, 정의된 상수, 모듈 전역 변수 등에 대한 스타일이 매우 다릅니다.변수 이름에는 유형이 포함됩니다.이름을 보고 해당 모듈이 속한 모듈, 범위 및 유형을 잘 알 수 있습니다.이를 통해 유형 등에 관련된 오류를 쉽게 감지할 수 있습니다.

다른 것들도 있지만 이것이 내 머리 꼭대기에 있습니다.

-아담

Answer 3

두 번째로 Jason의 제안을 따르겠습니다.

나는 주로 Perl로 작업하는 10-12명의 팀을 위한 표준 문서를 완성했습니다.이 문서는 "복잡한 데이터 구조에 대한 perltidy와 같은 들여 쓰기"를 사용한다고 말합니다. 우리는 또한이 표준을 충족하기 위해 코드를 정리할 수있는 예제 ontltidy 설정을 모두에게 제공했습니다.언어에 대한 매우 명확하고 업계 표준이 컸기 때문에 팀에서는 이에 대한 큰 구매를 했습니다.

이 문서를 작성하기 시작하면서 나는 저장소에 있는 훌륭한 코드의 몇 가지 예를 물어봤고, 템플릿을 구성하는 데 나보다 더 똑똑한 설계자가 할 수 있는 다른 표준 문서를 찾기 위해 검색을 조금 했습니다.마이크로 관리자 영역을 넘지 않고 간결하고 실용적이게 하는 것은 힘들었지만 그만한 가치가 있었습니다.데 어느 표준이 실제로 핵심입니다.

그것이 효과가 있기를 바랍니다!

Answer 4

분명히 언어와 기술에 따라 다릅니다.귀하의 예제 네임스페이스를 보면 Java를 추측할 것입니다. http://java.sun.com/docs/codeconv/ 시작하기 정말 좋은 곳입니다.모든 프로젝트를 비슷하게 보이게 만드는 Maven의 표준 디렉토리 구조와 같은 것을 살펴보고 싶을 수도 있습니다.