코딩 표준 문서 작성

나는 주요 작업이 SCADA 및 PLC 인 제어 시스템 회사에서 다른 제어 시스템과 함께 일합니다.

소프트웨어 개발은 ​​내부 프로젝트 관리 및 평가 시스템을 만들기로 결정하기 전까지는 회사가하는 일이 아닙니다.

이 프로젝트는 원래 소프트웨어 사용자로 온 사람들이 수행했으며 대부분 주니어입니다.

프로젝트는 소규모로 시작되었으므로 디자인, 데이터베이스 등과 같은 내용 만 문서화했지만 코딩 형식 / 컨벤션에 대해서는 결코 동의하지 않았습니다.

StyleCop 을 사용하여 문서를 잘 작성했는지 확인했지만 코딩 규칙 / 실습에 대한 공식 문서가 필요하다고 생각합니다. 그래야 좋은 표준을 계속 유지할 수 있고 앞으로 더 큰 개발 작업이있을 경우이를 처리하는 사람이 있습니다. 좋은 바닥 판이 있습니다.

거기에는 문제가 있습니다. 나는 코딩 규칙과 표준에 대한 문서를 작성하는 방법을 모릅니다. 내가 생각할 수있는 것은 좋은 대 나쁜 습관의 예입니다 (예 : 변수의 이름을 지정할 때 낙타의 경우 헝가리어 표기법을 피하는 등) 우리는 모두 유능한 프로그래머가있을 것입니다. 그러나 우리는 이런 종류의 헌장을 가지고 있지 않습니다.

그것을 지적하기 위해 내 질문은 : 좋은 코딩 표준 문서의 주요 측면과 내용은 무엇입니까?

좋은 코딩 표준 문서의 주요 측면과 내용은 무엇입니까?

1. 되는 코드의 검사 자동화 된 수있는 도구 지원 . 일부 규칙과 일치하지 않는 코드를 버전 제어 할 수 없다는 것을 알고 있다면 내 코드에서 해당 규칙을 따르는 것이 좋습니다. 반면에, 어떤 동료 프로그래머가 규칙을 따라야하는 곳에 글을 쓴다면, 나는 그 규칙에 대해 헛소리를 내지 않습니다.

2. 당신의 개인적인 의견 이 아니라 잘 생각하십시오 . "지금부터는 지역이 마음에 들지 않기 때문에 더 이상 지역을 사용하지 않습니다." 오히려 지역이 코드 성장을 장려하고 큰 문제를 해결하지 못한다고 설명 할 것 입니다.

   그 이유는 첫 번째 경우 동료 동료가 "글쎄, 나는 지역을 좋아하기 때문에 여전히 그들을 사용할 것"이라고 대답하기 때문입니다. 반면에 두 번째 경우에는 동의하지 않는 사람들이 건설적인 비판, 제안 및 주장을하도록 강요하여 결국에는 원래 의견을 바꾸게됩니다.

3. 잘 문서화 되고 있습니다 . 문서의 부족은 혼란과 해석의 여지를 만듭니다 . 혼란과 해석의 가능성은 스타일 차이, 즉 표준이 억제하고자하는 것의 원인이됩니다.

4. 인 회사 외부를 포함하여, 광범위한 . 20 명의 프로그래머가 사용하는 "표준"은 전 세계 수십만 명의 개발자가 알고있는 표준보다 표준이 아닙니다.

StyleCop에 대해 이야기하고 있기 때문에 응용 프로그램이 .NET Framework 언어 중 하나로 작성되었다고 가정합니다.

이 경우 다르게해야 할 심각한 이유가 없다면 Microsoft 지침을 따르십시오. 표준을 작성하는 대신 여러 가지 이점이 있습니다. 이전 4 가지 사항

1. 자신의 표준에 맞게 StyleCop 규칙을 다시 작성할 필요는 없습니다. 나는 자신의 규칙을 작성하는 것이 어렵다고 말하지는 않지만, 규칙을 피할 수 있다면, 대신 유용한 무언가를하는 데 더 많은 시간이 있다는 것을 의미합니다.

2. Microsoft의 지침은 매우 잘 알려져 있습니다. 당신이 그들 중 일부에 동의하지 않으면, 당신이 그것들을 이해하지 못했을 수도 있습니다. 이것은 나의 경우였습니다. C # 개발을 시작했을 때 몇 가지 규칙이 완전히 바보였습니다. 나는 그들이 왜 이런 식으로 쓰여 졌는지 마침내 이해했기 때문에 나는 그들에게 완전히 동의합니다.

3. Microsoft 지침은 잘 정리되어 있으므로 직접 문서를 작성할 필요가 없습니다.

4. 나중에 회사에 고용 될 새로운 개발자는 이미 Microsof의 코딩 표준에 익숙 할 것입니다. 내부 코딩 스타일에 익숙하지 않을 가능성이 있습니다.

가장 먼저 알아야 할 것은 코딩 표준 문서가 옳고 그름이 아니라는 것입니다. 그것은 좋고 나쁘거나 어떤 방법이 더 나은 것이 아닙니다.

코딩 표준 문서의 목적은 모든 코드가 동일하게 설계, 작성 및 배치되어 개발자가 다른 사람의 스타일을 읽을 필요없이 정신을 바꾸지 않고도 한 사람에서 다른 사람으로 전환 할 수 있도록하는 것입니다.

그것은 모두 통일성에 관한 것이며 "옳고 그른 것"에 관한 것은 아닙니다

이를 염두에두고 코딩 표준 문서에서 명확히해야 할 사항은 다음과 같습니다.

명명 규칙

메소드, 변수, 클래스 및 인터페이스의 이름을 어떻게 지정합니까? 어떤 표기법을 사용 하시겠습니까?

또한 표준에 포함 된 다른 것은 SQL에 대한 분리 표준이므로 테이블, 프로 시저, 열, id 필드, 트리거 등의 이름이 비슷했습니다.

들여 쓰기

들여 쓰기에 무엇을 사용 하시겠습니까? 단일 탭? 3 칸?

나열한 것

괄호가 오프닝 방법 라인과 동일한 라인에 유지됩니까? (일반적으로 java) 또는 다음 줄 또는 자체 줄? (일반적으로 C #)

예외 처리 / 로깅

예외 처리 및 로깅에 대한 표준은 무엇입니까? 모두 자란 것입니까, 아니면 타사 도구를 사용하고 있습니까? 어떻게 사용해야합니까?

댓글 달기

우리는 문법 정확성을 지시하는 표준을 가지고 있으며 주석은 같은 줄이 아니라 앞이나 뒤에서 시작하여 가독성을 높입니다. 주석은 코드와 같은 깊이로 들여 써야합니까? 더 큰 텍스트에 사용되는 주석 테두리를 허용합니까?

설명 방법에 대한 \\\는 어떻습니까? 이것들이 사용됩니까? 언제?

노출

모든 방법과 필드가 가능한 가장 낮은 수준의 액세스를 구현해야합니까?

또한 중요한 사항입니다. 좋은 표준 문서는 코드 검토에 도움이 될 수 있습니다.이 최소 표준을 충족합니까?

나는이 문서 중 하나에 들어갈 수있는 것의 표면을 간신히 긁었지만 KISS

길고 지루하고 통과하기가 불가능하거나 표준을 따르지 않을 경우 간단하게 유지하십시오.

나는이 과정을 여러 번 겪고있었습니다. 그리고 가장 성공적인 방법은 (어쨌든 울퉁불퉁하지만) 접근 방식은 잘 알려진 회사에서 "코딩 표준"문서를 가져와 필요에 맞게 수정하는 것이 었습니다.

예를 들어, 나는 이것을 발견했습니다 : http://www.tiobe.com/content/paperinfo/gemrcsharpcs.pdf

어쨌든 화염 방사기를 편리하게 유지하십시오.

건배,

나는 일반적으로 작은 물건을 땀을 흘리고 더 큰 그림을 무시하려고 할 때 대부분의 표준 문서를 싫어합니다.

예를 들어, 거의 모든 사람들이 변수 이름을 지정하거나 대괄호를 배치하는 방법을 말합니다. 이것은 순수한 스타일이며 개발자 코드 그룹을 올바르게 돕는 데 거의 도움이되지 않습니다. 디렉토리 구조 및 코드 레이아웃과 같은 것을 무시합니다. 연산자 사이에 얼마나 많은 공백을 두어야하는지, 메소드 사이에 얼마나 많은 빈 줄을 넣을지를 알려주는 표준 문서를 보았습니다. 이 모든 것들은 보통 규칙에 대한 예외로 끝납니다. 그들은 실제로 얼마나 무의미한 지 보여줍니다. 그런 다음 아무도 그들을 따라갈 수 없습니다. .

이제 저는 많은 다른 사람들로부터 다양한 소프트웨어 비트를 사용하며 모두 서로 다른 스타일을 가지고 있습니다. 나는 이것에 익숙해 져서 모든 개발 그룹에 공통된 스타일이 없다고 불평하지 않습니다. 코드가 프로젝트 전체에서 공통적 인 스타일이라면 그 스타일이 무엇인지는 중요하지 않습니다. 모든 표준 문서에 대한 첫 번째 규칙은 다음과 같습니다 . 프로젝트 내에서 일관된 코딩 스타일을 유지하십시오 . 괄호가 모두 같은 한, 아무도 무화과를 제공해서는 안됩니다. 종교적 전쟁을 겪고 그들을 밀어 :)

두 번째는 코드 레이아웃입니다. 코드 조각을 집어 들었을 때 코드가 다른 유사한 작업과 비슷한 줄을 따라 배치되어 있는지 확인하고 싶습니다. 웹 서비스가 있다면 wsdl 계약의 이름을 명확하게하고 싶습니다. 구현 이름을 명확하게하고 싶습니다. 나는 누군가가 파일과 클래스에 대해 새롭고 다른 레이아웃을 생각해 내기를 원하지 않습니다. 그것은 내가 성가신 "코드 찾기"를해야한다는 것을 의미합니다. 마지막으로 작업 한 프로젝트와 동일하게 보이면 원하는 것을 찾을 수있는 위치를 즉시 알 수 있으며 아마도 내가 아는 다른 사람들의 코드로 작업하는 데 가장 큰 도움이 될 것입니다. 따라서 코드가 배치되는 방식의 구조를 유지하십시오 (예 : 문서 용 문서 폴더, 인터페이스 용 인터페이스 등).

코드 아티팩트도 있어야하므로 예상되는 오류 처리가 예외인지 아니면 오류 코드인지를 말해야합니다. 사용중인 아키텍처 기능을 문서화하십시오 . 또한 어떤 종류의 로깅을 사용하는지, 사용자에게 로그 / 오류 처리를 제공하는 방법 또는 코드를 관리하는 데 사용되는 모든 하위 시스템을 설명해야합니다. 나는 모든 프로젝트가 다르게 로깅 된 곳에서 일했습니다. 각 코드 릴리스가 어떻게 운영 체제에 문제가 있는지 알려주는 방법을 알려주는 고유 한 다른 운영 문서를 가지고 있어야하는 방법은 한심했습니다. 이벤트 로그, 로그 파일 (이 경우)은 모두 여기에서 유효합니다. 코드를 구성하는 방법 (일부 프로그램의 경우 .config 파일 또는 사용자 지정 DB, 명령 줄 매개 변수 또는 다른 것의 레지스트리는 사용하지 않음)과 같은 다른 일반적인 측면에도 동일하게 적용됩니다.

요컨대, 중요한 것은 일관성 입니다. 그리고 거대한 표준 문서는 너무 많이 읽고 기억하기 때문에 사람들이 볼 수없는 것들 (예 : 로깅과 같은 건축 표준)을 알리고 현재 작성한 것과 일치하는 코드를 유지하도록 지시하는 것을 선호합니다. 그리고 아직 코드가 없다면 표준 문서가 필요하지 않습니다! (글쎄, 당신이 그것을 쓸만큼 충분히 쓸 때까지).

그래서 요점이 걸릴 : 법적 문서를 만들려고하지 않습니다 , 단지 코딩하지 않는 것을 생각뿐만 아니라 어떻게 코드가 작동하는 방법과 다른 사람의 기대와 코드 맞는. 그런 다음 사람들이 좋은 코드를 작성하도록 믿으면 그들이하는 것을 보게 될 것입니다. (그리고 그들이 당신이 그들과 함께 단어를 가질 수 없다면, 법처럼 그것을 내려 놓을 필요가 없습니다).

시간과 에너지를 낭비하는 것은 아닙니다. StyleCop은 훌륭하고 수년에 걸쳐 귀 하나 팀원보다 훨씬 더 숙련되고 똑똑한 사람들에 의해 설립되었습니다. 포용하고 사랑하십시오! 그것은 당신을 지속적으로 안내하는데, 그것은 귀찮게 읽을 수있는 누군가를 기다리는 어떤 문서보다 낫습니다.