Java API와 같이 잘 문서화 된 코드의 좋은 예가 있습니다. 그러나 git 및 회사 내부 프로젝트와 같은 공개 프로젝트의 많은 코드는 문서화가 제대로되어 있지 않으며 초보자에게 친숙하지 않습니다.

모든 소프트웨어 개발 과정에서 문서화가 잘되지 않은 코드를 다루어야했습니다. 다음과 같은 사항을 발견했습니다.

  1. 코드에 주석이 거의 없거나 전혀 없습니다.
  2. 메소드 및 변수 이름은 자체 설명이 아닙니다.
  3. 코드가 시스템 또는 비즈니스 프로세스에 어떻게 부합하는지에 대한 문서가 거의 또는 전혀 없습니다.
  4. 나쁜 개발자를 고용하거나 좋은 개발자를 멘토링하지 않습니다. 그들은 간단하고 깨끗한 코드를 작성할 수 없습니다. 따라서 개발자를 포함하여 누구에게나 코드를 문서화하는 것은 어렵거나 불가능합니다.

결과적으로 저는 많은 과정을 거쳐야했습니다. 코드를 작성하고 많은 사람들과 대화하여 무언가를 배우는 것이 모든 사람의 시간 낭비라고 생각합니다. 또한 프로젝트에 새로 온 사람들을위한 KT / 지식 이전 세션이 필요합니다.

다음과 같은 이유로 인해 문서에 대한주의가 필요하지 않다는 것을 알게되었습니다.

  1. Laziness.
  2. 개발자는 코드 외에는 아무것도하지 않습니다.
  3. 작업 보안. (아무도 코드를 쉽게 이해할 수 없다면 쉽게 교체 할 수 없을 수도 있습니다.)
  4. 기한이 까다로워 문서화 할 시간이 거의 없습니다.

그래서 회사 나 프로젝트에서 좋은 문서화 관행을 장려하고 시행 할 방법이 있는지 궁금합니다. 전략은 무엇입니까? 복잡성에 관계없이 모든 프로젝트의 시스템 및 코드에 대한 적절한 문서를 작성하는 데 사용됩니다. 문서가 최소한으로 필요하거나 전혀 필요하지 않은 경우에 대한 좋은 예가 있습니까?

IMHO, 우리는 프로젝트가 전달 된 후 문서 검토. 단순하고 간결하며 설명적이고 사용자 친화적이지 않은 경우 개발자 또는 기술 문서 엔지니어가 이에 대한 책임을지고이를 수정해야합니다. 나는 사람들이 문서를 다량으로 만들 것을 기대하지 않습니다. 헤드 퍼스트 책처럼 사용자 친화적 이길 바라지는 않지만, 시간의 분석과 낭비적인 KT 세션.

이 광기를 끝내거나 완화 할 수있는 방법이 있습니까? “문서 중심 개발”아마도?

댓글

  • 적절한 문서가없는 또 다른 이유가 있습니다. 그렇지 않은 좋은 문서를 작성하는 것은 매우 어렵습니다. ' 코드를 영어로 의역 할뿐만 아니라 코드가 그렇게 설계 / 작성된 이유 를 설명합니다. 이 정보에 대한 필요성은 기록 된 지 후 몇 달 후에야 분명해집니다.
  • 또 다른 심각한 이유 : 많은 개발자가 영어를 제 2 언어로 사용하거나 영어를 잘못 쓰는 것입니다. . 방법에 대해 한 줄로 작성하도록 강요 할 수도 있지만, 좋은 문서를 원한다면 비용을 지불 할 준비가되어 있고 전문가를 고용하여 수행 할 수 있습니다.

답변

코드 문서화 방법

이미 힌트가 있습니다. Java API가 문서화되는 방식을 살펴보십시오.

보다 일반적으로 모든 프로젝트에 적용되는 고유 한 규칙 세트는 없습니다. 업무상 중요한 대규모 프로젝트를 작업 할 때 문서는 소규모 오픈 소스 라이브러리 용으로 작성하는 문서와 아무 관련이 없습니다. 즉, 중간 규모의 개인 프로젝트 문서와 관련이 없습니다. .

왜 많은 오픈 소스 프로젝트가 잘 문서화되어 있지 않나요?

대부분의 오픈 소스 프로젝트는 재미 있기 때문에 프로젝트에 기여한 사람들에 의해 만들어지기 때문입니다. 대부분의 프로그래머와 개발자는 문서 작성은 무료로 할 수있을만큼 재미 있지 않습니다.

왜 많은 비공개 프로젝트 잘 문서화되어 있지 않습니까?

(1) 좋은 문서를 작성하고 (2) 유지하는 데 막대한 비용이 들기 때문입니다.

  1. 즉시 비용 (문서 작성 비용)은 이해 관계자가 명확하게 볼 수 있습니다. 팀이 프로젝트를 문서화하는 데 향후 2 개월을 소비하도록 요청하면 2 개월의 추가 급여를 지불해야합니다.

  2. 로 기간 비용 (문서 유지 비용)은 관리자에게도 매우 쉽게 눈에 띄게되며 비용을 낮추거나 지연을 줄여야 할 때 첫 번째 목표가되는 경우가 많습니다. 이로 인해 빠르게 쓸모 없게되고 업데이트하는 데 매우 많은 비용이 드는 오래된 문서의 추가 문제가 발생합니다.

  3. 장기적 절약 (몇 일을 탐색하는 데 낭비하지 않아도 됨으로 인한 절약) 반면에 몇 년 전에 문서화 했어야하는 기본적인 것을 이해하기위한 레거시 코드)는 측정하기 어렵습니다. 이는 문서를 작성하고 유지하는 것이 시간 낭비라는 느낌을 일부 관리자에게 확인시켜줍니다.

내가 자주 관찰하는 것은 다음과 같습니다.

  1. 처음에는 팀이 많은 것을 문서화하려고합니다.

    p>

  2. 시간이 지남에 따라 기한의 압박과 관심 부족으로 인해 문서를 유지하기가 점점 더 어려워집니다.

  3. 몇 달 나중에 프로젝트에 참여한 새로운 사람은 실제 시스템과 전혀 일치하지 않기 때문에 실제로 “문서를 사용할 수 없습니다.

  4. 이 사실은 경영진이 개발자를 비난합니다. 문서를 유지하지 않기 위해; 개발자는 업데이트에 몇 주를 소요하도록 요청합니다.

    • 경영진이 몇 주를 허용하면주기가 반복됩니다.

    • 경영진이 이전 경험을 기반으로 거부하면 제품에 문서가 없기 때문에 나쁜 경험이 증가 할 뿐이지 만이를 작성하고 유지하는 데 몇 달이 소요되었습니다.

문서화는 테스트와 마찬가지로 지속적인 프로세스 여야합니다. 일주일에 수천 개의 LOC를 코딩하기 만하면 테스트 및 문서로 돌아가는 것은 매우 고통 스럽습니다.

팀이 작성하도록 권장하는 방법 문서?

사람들이 깨끗한 코드를 작성하거나, 정기적 인 리팩토링을 수행하거나, 디자인 패턴을 사용하거나, 충분한 단위 테스트를 추가하도록 장려하는 방법과 유사합니다.

  • 예를 들면. 당신이 좋은 문서를 작성한다면, 당신의 짝들도 그렇게하기 시작할 것입니다.

  • 문서 검사를 목표로하는 공식적인 코드 리뷰를 포함하여 체계적인 코드 리뷰를하십시오.

  • 팀의 일부 구성원이 특히 좋은 문서 (또는 문서)에 대해 반감을 품는 경우, 더 나은 문서를 작성하는 데 방해가되는 장애물이 무엇인지 이해하기 위해 해당 주제에 대해 개인적으로 논의합니다. 그들이 시간 부족을 탓하면 문제의 원인을 알 수 있습니다.

  • 몇 주 또는 몇 달 동안 문서의 존재 또는 부족을 측정 할 수 있도록하지만 그렇게하지 마십시오. 예를 들어 LOC 당 댓글 줄 수를 측정 할 수 있지만 영구적으로 측정하지 마세요. 그렇지 않으면 개발자가 낮은 점수를 제거하기 위해 길지만 의미없는 댓글을 작성하기 시작합니다.

  • 게임 화를 사용하세요. 이것은 이전 요점과 함께 제공됩니다.

  • 긍정적 / 부정적 강화 를 사용합니다.

  • ( SJuan76의 댓글 참조) 댓글 부족을 오류로 처리합니다. 예를 들어 Visual Studio에서 XML 문서를 생성하는 옵션을 확인할 수 있습니다. 또한 모든 경고가 오류로 취급되는지 확인하는 경우 클래스 또는 메서드의 맨 위에 주석이 없으면 컴파일이 중단됩니다.

    이전 세 가지 요점은이 점을 사용해야합니다. 조심해서. 저는 초보 프로그래머로 구성된 특히 힘든 팀과 함께 잠시 동안 사용했으며 다음과 같은 StyleCop 호환 주석으로 끝났습니다. 

  /// <summary> /// Gets or sets the PrimaryHandling. /// </summary> public Workflow PrimaryHandling { get; set; }

음 … 특별히 도움이되지 않았습니다.

기억 : 프로그래머가 실수하고 싶을 때 잘못된 댓글을 정확히 찾아내는 데 자동화 된 것은 없습니다 . 전용 코드 검토 및 기타 인간 작업이 도움이 될 것입니다.

문서가 최소한으로 필요하거나 전혀 필요하지 않은 경우에 대한 좋은 예가 있습니까?

아키텍처 및 디자인을 설명하는 문서 는 필요하지 않습니다.

  • 시제품의 경우

  • 작업을 완료하기 위해 몇 시간 안에 작성된 개인 프로젝트의 경우이 프로젝트는 더 이상 유지되지 않을 것입니다.

  • 명백한 프로젝트의 경우 특히 깨끗한 코드와 함께 작은 크기로 코드를 탐색하는 미래의 모든 관리자보다 문서 작성에 더 많은 시간을 할애 할 것입니다.

인 코드 문서 (코드 주석)가 필요하지 않습니다. 그들에게있어 코멘트의 존재는 드문 경우를 제외하고는 좋은 징조는 아니지만, 코멘트 없이는 코드가 명확하게 리팩토링되지 않았다는 신호입니다.

프로젝트가 전달 된 후 문서 검토를 받아야한다고 생각합니다.

최소한 프로젝트가 전달 된 경우 일주일에 한 번, 그렇게해야합니다. 프로젝트가 민첩하지 않고 6 개월 간격으로 제공되는 경우 더 정기 검토를 수행하십시오.

댓글

  • ' 장려하는 방법 ', 많은 IDE가 누락 된 문서에 대한 알림을 경고로 허용한다고 추가합니다. 또는 OSB에서 문서의 정적 분석을 수행 할 수 있습니다 (물론 그것만으로는 충분하지 않습니다).
  • @ SJuan76 : 그렇습니다. Visual Studio는 주석 부족을 컴파일 타임 오류로 처리 할 수도 있습니다. 이에 대한 메모를 추가하기 위해 제 답변을 편집했습니다.
  • @ArseniMourzenko-문서화를위한 스토리를 추가하여 Agile에서 일부 문서화를 권장 할 수 있다고 읽었습니다. 그러나 이것들이 다른 이야기, 즉 완료의 다른 이야기 정의를 차단해서는 안되며, 문서화 이야기의 완성을 포함해서는 안됩니다. 어떻게 들리나요?
  • @ArseniMourzenko-저는 ' 답변에 2 점을 더 추가하고 싶습니다. (1) Jira 등에서 항상 문서화 작업을 추가합니다. (2) 2 명이 추가로 문서를 검토하도록 & 작업으로 지정합니다. 이렇게하면 사람들에게 & 문서를 작성하라는 알림을 받게됩니다 (검토로 인해) 저품질 문서 작성을 피할 수 있습니다. 우선 순위를 지정하지 않으면 ' & 검토하면 상태가 나빠집니다. 저는 Amazon이 문서 검토를 많이하는 & 문서 검토를 너무 많이한다는 것을 알고 있습니다.

답변

댓글과 문서를 구분해야한다고 생각합니다. 주석은 설명 적이지만 일관성이 부족하며 코드 전체에 흩어져 있습니다. 주석은 자기 설명이 충분하지 않은 코드를 보상해서는 안되며, 대신 다른 프로그래머에게 까다로운 부분을 암시해야합니다.

코드를 문서화할지 여부는 프로젝트의 규모에 따라 다릅니다. 분명히 모든 것 이 문서화되어야한다고 믿는 사람들이 있으며, 누가 감히 반대 할 것이기 때문에 그 생각을 정당화하기가 쉽습니다. 지식 문서화? 다행히 소프트웨어 개발은 과학이 아닙니다. 작은 프로그램의 세부 사항이 모호해 져도 세상은 무너지지 않습니다. 이제 많은 개발자가 사용하는 전문 소프트웨어에 관해서는 분명히 코드를 문서화해야합니다.하지만 그 자리에 있다면 그 수준에서 코드를 작성한다면 당연히 알고있을 것입니다.

tl; dr

모든 프로젝트가 잘 문서화되도록 요구한다면 너무 많은 것을 요구하는 것입니다. .

댓글

  • Fortunately software development is not science 이것을 믿는 이유에 대해 자세히 알려주세요.
  • @Borat-소프트웨어 개발은 공학 분야로, 과학이 제공 한 도구를 사용함을 의미합니다.
  • 모든 것을 문서화하도록 요구하는 것이 아닙니다. 시스템과 코드가하는 일에 대한 높은 수준의 개요를 제공하기에 충분합니다. 예 : 내 TV 사용 방법을 알려주세요. LCD, CRT, CRT를 사용하는지 ' 작업을 완료하기위한 진공관 또는 고체 상태 장치 . 수리공이 그 정보를 원하면 별도의 문서를 만드십시오.
  • 높은 수준의 개요를 원하면 식별자 이름으로 충분합니다. TV의 버튼에 " 켜기 " 레이블이있을 수있는 것과 같습니다. 그래서 당신은 낮은 수준의 세부 사항을 요구하고 있습니다.
  • @LeopoldAsperger : Borat는 클래스의 메서드가 아니라 아키텍처와 디자인을 문서화하는 것에 대해 이야기하고 있다고 생각합니다.

답글 남기기

이메일 주소를 발행하지 않을 것입니다. 필수 항목은 *(으)로 표시합니다