코드 문서화를 수행하는 방법과 소프트웨어 (종종)의 문서화가 왜 좋지 않습니까?

java api와 같이 잘 문서화 된 코드의 좋은 예가 있습니다. 그러나 git 및 회사의 내부 프로젝트와 같은 공개 프로젝트의 많은 코드는 문서화가 잘되어 있지 않으며 새로 온 사람에게는 적합하지 않습니다.

모든 소프트웨어 개발 문제에서 제대로 문서화되지 않은 코드를 처리해야했습니다. 나는 다음과 같은 것을 알아 차렸다.

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

결과적으로 많은 코드를 거쳐 많은 사람들과 이야기를 나눠야했습니다. 나는 이것이 모두의 시간을 낭비한다고 생각합니다. 또한 신규 이민자를위한 KT / 지식 이전 세션이 필요합니다.

나는 다음과 같은 이유로 문서에 주목할 필요가 없다는 것을 배웠다.

1. 게으름.
2. 개발자는 코드 이외의 작업을 좋아하지 않습니다.
3. 고용 안정. (아무도 코드를 쉽게 이해할 수 없으면 쉽게 교체 할 수 없습니다.)
4. 어려운 마감일은 기록 할 시간이 거의 없습니다.

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

IMHO, 프로젝트가 완료된 후 문서 검토를 받아야한다고 생각합니다. 간단하고 간결하며 설명이 풍부하고 사용자에게 친숙하지 않은 경우 개발자 또는 기술 문서 엔지니어는 이에 대한 책임을 갖고 수정해야합니다. 나는 사람들이 문서를 많이 만들 것으로 기대하지 않으며, 첫 번째 책처럼 사용자 친화적이기를 희망하지는 않지만 몇 시간의 분석과 낭비적인 KT 세션이 필요하지 않을 것으로 기대합니다.

이 광기를 끝내거나 완화시키는 방법이 있습니까? "문서 중심 개발"?

코드를 문서화하는 방법?

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

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

많은 오픈 소스 프로젝트가 문서화되지 않은 이유는 무엇입니까?

대부분의 오픈 소스 프로젝트는 재밌기 때문에 해당 프로젝트에 참여하는 사람들이 제작하기 때문입니다. 대부분의 프로그래머와 개발자 는 문서 작성이 무료로 하기에는 충분히 재미 있지 않다고 생각합니다 .

많은 폐쇄 소스 프로젝트가 잘 문서화되지 않은 이유는 무엇입니까?

(1) 좋은 문서를 작성하고 (2) 문서를 유지하는 데 많은 비용이 듭니다.

1. 즉각적인 비용 (문서 작성 비용)은 이해 당사자들에게 분명하게 드러납니다. 팀이 다음 2 개월 동안 프로젝트를 문서화하도록 요청하는 경우 2 개월의 추가 급여를 지불해야합니다.

2. 장기 비용 (문서 유지 비용)은 관리자에게도 매우 눈에 띄게되며 비용을 낮추거나 지연을 단축해야하는 첫 번째 대상이되는 경우가 많습니다. 이로 인해 구식 문서의 추가 문제가 발생하여 빠르게 쓸모없고 업데이트 비용이 매우 비쌉니다.

3. 반면에 장기적인 저축 (몇 년 전에 문서화해야 할 기본 사항을 이해하기 위해 레거시 코드를 탐색하는 데 며칠을 낭비하지 않아도되는 저축)은 측정하기가 어려워 일부 관리자의 느낌을 확인시켜줍니다. 문서 작성 및 유지 관리는 시간 낭비입니다.

내가 자주 관찰하는 것은 :

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

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

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

4. 경영진은 문서를 유지 관리하지 않은 개발자를 비난합니다. 개발자는 몇 주 동안 업데이트를 요청합니다.

   • 관리에 몇 주가 걸리면주기가 반복됩니다.

   • 이전 경험을 바탕으로 경영진이 거부하면 제품에 문서가 부족하기 때문에 나쁜 경험 만 증가 시키지만 몇 달 동안 작성하여 유지 관리하는 데 소비되었습니다.

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

팀에게 문서 작성을 독려하는 방법?

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

• 예를 들면. 좋은 문서를 작성하면 쌍도 그 일을 시작할 수 있습니다.

• 문서 검사를 대상으로하는 공식 코드 검토를 포함하여 체계적인 코드 검토를 수행하십시오.

• 팀의 일부 구성원이 특히 좋은 문서 (또는 문서)에 대해 반감을 갖고 있다면, 더 나은 문서를 작성하지 못하게하는 장애가 무엇인지 이해하기 위해 주제를 개인적으로 논의하십시오. 그들이 시간 부족을 비난하면 문제의 원인을 볼 수 있습니다.

• 몇 주 또는 몇 달 동안 문서의 유무를 측정 할 수 있지만 그에 초점을 두지 마십시오. 예를 들어 LOC 당 주석 줄 수를 측정 할 수 있지만 영구적으로 측정하지는 않습니다. 그렇지 않으면 개발자는 낮은 점수를 없애기 위해 길지만 의미없는 주석을 작성하기 시작합니다.

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

• 포지티브 / 네거티브 강화를 사용하십시오 .

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

  이전의 세 가지 점에 대해서는이 점을주의해서 사용해야합니다. 나는 특히 초보자 프로그래머 팀과 함께 잠시 동안 그것을 사용했으며, 다음과 같이 StyleCop 호환 주석으로 끝났습니다.

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

흠 ...별로 도움이되지 않았습니다.

기억하십시오 : 프로그래머가 당신을 망치고 싶을 때 나쁜 의견을 찾아내는 데 도움이되는 자동화 된 것은 없습니다 . 코드 검토 및 기타 휴먼 타스크 만 도움이됩니다.

문서가 최소한이거나 필요하지 않은 좋은 예가 있습니까?

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

• 프로토 타입의 경우

• 작업을 수행하기 위해 몇 시간 안에 작성된 개인 프로젝트의 경우이 프로젝트가 더 이상 유지되지 않을 것임을 확신하면서,

• 크기가 작고 특히 깨끗한 코드와 함께 분명한 프로젝트의 경우 모든 미래의 관리자가 코드를 탐색하는 것보다 문서를 작성하는 데 더 많은 시간을 소비하게됩니다.

코드가 자체 문서화 될 때 일부 개발자에 따르면 코드 내 문서 (코드 주석)가 필요하지 않습니다. 그들에게있어 주석의 존재는 드문 경우를 제외하고는 좋은 징조가 아니라 주석이 필요하지 않은 코드를 명확하게 리팩토링하지 않았다는 징조입니다.

프로젝트가 전달 된 후 문서 검토가 필요하다고 생각합니다.

프로젝트가 일주일에 한 번 이상 제공되면 바로 갈 수 있습니다. 프로젝트가 민첩하지 않고 6 개월 간격으로 제공되는 경우보다 정기적 인 검토를 수행하십시오.

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

코드를 문서화해야하는지 여부는 프로젝트 규모에 따라 다릅니다. 분명히 모든 것이 문서화되어야 한다고 믿는 사람들 이 있으며, 문서화 지식에 반대하는 사람이 누구인가에 대해 그 생각을 정당화하는 것이 쉬운 것 같습니까? 운 좋게도 소프트웨어 개발은 ​​과학이 아니며 작은 프로그램의 세부 사항이 모호해지면 세상이 무너지지 않습니다. 많은 개발자들이 사용할 전문 소프트웨어와 관련하여 코드를 문서화해야합니다. 그러나 해당 레벨에서 코딩 할 수있는 위치에 있다면 분명히 알 것입니다.

tl; dr

모든 프로젝트를 잘 문서화하도록 요구하면 너무 많이 요구하는 것입니다.