하이퍼 링크, 외부화 된 소스 코드 문서 [닫기]

소스 코드의 왜 우리는 여전히 포함 않는 자연 언어 설명 (즉, 이유 왜 코드의 라인이 작성된)이 아니라 별도의 문서로보다, 소스 코드 내에서?

현대 개발 환경 (고해상도 모니터, 듀얼 모니터 등)에 제공되는 광범위한 부동산을 고려할 때, IDE는 소스 코드가 시각적으로 분리되어 있지만 본질적으로 연결되어있는 반 잠금 단계 패널을 제공 할 수 있습니다. 해당 의견. 예를 들어, 개발자는 하이퍼 링크 마크 업 언어로 소스 코드 주석을 작성할 수 있으며 (추가 소프트웨어 요구 사항에 연결됨) 문서가 소스 코드를 복잡하게 만드는 것을 동시에 방지 할 수 있습니다.

그러한 소프트웨어 개발 메커니즘을 방해하는 단점은 무엇입니까?

질문을 명확하게하는 모형 :

커서가 소스 코드의 특정 라인에있을 때 (위의 파란색 배경으로 표시됨) 커서의 라인에 해당하는 문서가 강조 표시됩니다 (즉, 다른 세부 사항과 구별됨). 질문에서 언급했듯이, 커서가 소스 코드를 뛰어 넘을 때 문서는 소스 코드와 잠금 단계를 유지합니다. 단축키는 "문서 모드"와 "개발 모드"사이를 전환 할 수 있습니다.

잠재적 장점은 다음과 같습니다.

• 한 번에 화면에 더 많은 소스 코드와 더 많은 문서
• 언어와 상관없이 소스 코드와 독립적으로 문서를 편집하는 기능
• 병합 충돌없이 문서 및 소스 코드를 병렬로 작성
• 뛰어난 텍스트 형식의 실시간 하이퍼 링크 문서
• 다른 자연 언어로의 준 실시간 기계 번역
• 모든 코드 줄은 작업, 비즈니스 요구 사항 등에 명확하게 연결될 수 있습니다.
• 각 코드 줄을 작성할 때 문서가 자동으로 타임 스탬프를 만들 수 있음 (메트릭)
• 아키텍처 다이어그램, 관계를 설명하기위한 이미지 등의 동적 포함
• 단일 소스 문서 (예 : 사용자 수동 포함을위한 태그 코드 스 니펫)

노트 :

• 설명서 창을 축소 할 수 있습니다
• 소스 파일을 보거나 비교하는 워크 플로우는 영향을받지 않습니다.
• 어떻게 구현이 발생하는 것은 세부입니다; 설명서는 다음과 같습니다.
  • 소스 파일의 끝에 유지;
  • 규칙 ( filename.c, filename.c.doc) 으로 두 파일로 분할합니다 . 또는
  • 완전 데이터베이스 중심
• 하이퍼 링크 된 문서 란 외부 소스 (예 : StackOverflow 또는 Wikipedia) 및 내부 문서 (예 : 비즈니스 요구 사항 문서를 상호 참조 할 수있는 하위 도메인의 위키) 및 기타 소스 파일 (JavaDoc과 유사)에 링크하는 것을 의미합니다.

관련 글타래 (쓰레드) : 업계에서 문서화를 혐오하는 것은 무엇입니까?

이 문제는 항상 나를 귀찮게하고, 우리가 시도하고 해결해야 할 방향에 대한 아이디어를 얻었습니다 (그래서이 질문을 찾은 방법).

소스 코드에 사용자 문서를 포함하기로 결정했을 때 연결된 문서 문제가 잘못되었다고 생각합니다. docco처럼.

우선, 코드 주석을 사용자 문서와 차별화 할 수 있습니다.

코드 주석은 일반적으로 짧고 실제로 매우 짧을 때 가장 좋습니다. 그래서 실제로 왜 그리고 어떻게 작동하는지에 대한시를 보지 않고도 물건을 수행하는 코드를 읽을 수 있습니다.

사용자 의견은 라이브러리 / API를 사용하려는 사람들을위한 것이며, 사용 예제, 구현 이유 설명 또는 라이브러리 확장 방법에 대한 지침이 포함될 수 있습니다. 이런 종류의 의견은 정말 장황한 경향이 있습니다.

문서를 일반 텍스트로 작성해야하므로 공급 업체에서 수정하지 않았으며 VCS에 쉽게 추가 할 수 있습니다. 그러나 사용자 문서를 소스 파일에 보관하는 것은 적어도 두 가지 이유로 큰 실수라고 생각합니다.

• 코드를 읽기 어렵다
• 충분히 유연하지 않은 문서 (동일한 예제 코드를 사용하거나 두 개의 다른 소스 파일에서 코드를 인터리브해야하는 하나의 문서 페이지가 있어야 함).

왜 같은 파일에 저장하고 싶습니까? 글쎄, 아무도 문서를 코드와 동기화하지 않기를 원하지 않습니다. 그러나 우리는 어쨌든, 특히 Markdown의 큰 성공을 거두며 특히 그렇습니다. 내가 올바른 길을 가고 있다고 생각하지만 부족하면 짧습니다.

코드 주석을 사용자 주석과 인터리브하면 양방향 바인딩이 있습니다. 이를 통해 어떤 주석이 코드의 어떤 부분에 해당하는지 쉽게 알 수 있습니다. 일부 코드가 문서화되지 않은지도 확인할 수 있습니다. 그것이 제공하지 않는 것은 주석이 업데이트되었는지 여부를 확인하는 방법이며 코드가 읽기 어려울 때 (문서가보기 싫기 때문에) 많이 발생합니다.

양방향 바인딩 대신에 한 가지 방법이 있다면 어떨까요? 코드를 가리키는 설명서 다음과 같은 특수 명령으로 마크 다운 코드를 가질 수 있습니다.

Some documentation right here that explains the following code:
   @include_file <path/to/some/file>:<line_start>-<line_end>
or
   @include_file <path/to/some/file>
     @starts_with "some regexp or literal text to search"
     @ends_with "another regexp"
or
   @include_file <path/to/some/file>
     @class MyClass
     @method foo
or any combination or way of linking you could imagine

We can even have semantic in the directives:
   @explain_code <path/and/same/of/above>
   @example_code <path/and/same/of/above>
   @performance_notice <path/and/same/of/above>

Which would do basically the same, but it adds the intention of why
do we want to add this code in the first place, which could be 
used different by an IDE. 

이것은 몇 가지 추가 사항으로 마크 업되는 이점이 있으며 적절한 도구를 사용하면 더 많은 가치를 창출 할 수 있습니다.

그런 식으로 툴링과 같은 툴을 사용한다고 상상해보십시오 (심지어 워치 작업에서도). 소스 파일이 언제 변경되는지 감지하고 그에 종속 된 문서 파일을 확인하고 주석 처리 된 코드가 변경되었는지 사용자에게 경고하거나 어딘가에 표시하십시오.

404 페이지를 찾을 수 없음

코드로 작업 할 때 주석이 손실되는 것을 원하지 않으므로 코드와 주석을 별도의 문서로 분리 할 때 발생합니다.

또한 주석 문서와 코드 문서 사이의 버전을 유지하면 더 많은 고통이 생길 수 있습니다.

내가 제안한 일부 제안은 실제로 좋아하지만 1 파일에 코드와 주석이있는 동안 쉽게 구현할 수 있습니다.

내가 볼 수있는 가능한 단점 :

• 이 기능을 구현하는 특수 편집기가 필요합니다

• 코드는 더 이상 일반 텍스트가 아니며 VCS-es를 조작하고 커밋하기 쉽습니다.

• 코드를 사용하려면 화면 너비가 두 배 더 필요합니다

당신의 주장에 관해서 :

한 번에 화면에 더 많은 소스 코드와 더 많은 문서

그러나 두 파일을 나란히 보려면 ​​불편할 수 있습니다.

언어와 상관없이 소스 코드와 독립적으로 문서를 편집하는 기능

나는 그것이 실제로 단점이라고 주장 할 것이다. 나는 개인적으로 문서를 가능한 한 코드와 가깝게 유지하여 구식이되지 않도록 노력합니다.

병합 충돌없이 문서 및 소스 코드를 병렬로 작성

다시, 아마도 단점. 문서가 코드에 깊이 삽입되어 있다면 어떻게 독립적으로 편집 할 수 있습니까?

뛰어난 텍스트 형식의 실시간 하이퍼 링크 문서

코드에 있으면 이미 실시간입니다.;) 하이퍼 링크의 경우 대부분의 IDE에서 정의로 점프하는 것이 이미 구현되어 있습니다.

다른 자연 언어로의 준 실시간 기계 번역

왜 당신이 규칙적인 주석 / 문서 문자열로 그렇게 할 수 없는지 모르겠습니다.

모든 코드 줄은 작업, 비즈니스 요구 사항 등에 명확하게 연결될 수 있습니다.

이것은 확실하지 않습니다 ... 정기적 인 의견으로는 달성 할 수 없습니까?

각 코드 줄을 작성할 때 문서가 자동으로 타임 스탬프를 만들 수 있음 (메트릭)

VCS-es가 이미 이런 종류의 정보를 제공하지 않습니까?

이것을 말했듯이 레이아웃 자체가 마음에 들지만 파일 형식을 변경할 필요가 없어 일반 주석에서 생성하는 것이 어렵지 않습니다. Docco 와 Pycco 또는 Marginalia 와 같은 후속 문서와 같은 문서 생성기가 많이 있습니다.

먼저, 문서 주석은 코드와 함께 진행해야합니다. 코드를 다른 곳으로 옮기면 실제로 제로 게인을 처리하기가 매우 어려워집니다. 그래서 왜 귀찮게!

할 수있는 일은 포함 된 주석을 가져 와서 편집기에서 숨겨서 풍선이나 툴팁 또는 필요에 따라 표시하지 않는 것입니다. 그러한 접근 방식으로 사람들이 코드에 훨씬 더 많은 문서를 작성하도록 장려 할 수 있기를 바랍니다. 예를 들어 클래스에 대한 설명은 외부 디자인 문서가 아니라 클래스와 함께 갈 수 있습니다.

현재 코드 주석에 하이퍼 링크를 포함시킬 수 있으며 Doxygen 또는 Sphinx와 같은 도구를 사용하여 코드에서 문서를 생성 할 수 있습니다. 이 도구를 더 잘 지원하기 위해 코드 편집기를 사용하려면 멋진 확장 기능이 필요합니다.

코드 줄을 버그 추적기 또는 요구 사항 도구에 연결하지 않으므로 SCM에 더 적합합니다. 그런 다음 작업에 연결된 커밋 당 코드 편집을 볼 수 있습니다. 코드에 저장된 문서를 버그 추적기와 통합하지 않을 것입니다. 새로운 문서로 마이그레이션하려는 경우 망할 수 있습니다 (음, 지금이 기능이 TFS에 추가 된 것을 볼 수 있습니다). 커밋 기록을 잃어 버렸습니다

@Bogdan이 이미 말한 것 외에도 몇 가지를 추가 할 것입니다.

• IDE는 항상 한 번에 2 개의 파일을 갖도록 구성했습니다. 제안한 기능을 사용하면 기본적으로 동일한 양의 정보를 보려면 2 대의 모니터가 필요하고 2로 현재하고있는 작업을 수행하려면 3 대의 모니터가 필요합니다.
• 파일을 탐색하는 동안 주석을 즉시 볼 수 없으며 원하는 내용을 정확히 모를 경우 찾기가 매우 어렵습니다.
• 파일을 검색하는 동안 주석을 직접 (또는 쉽게) 검색 할 수 없습니다.
• 때로는 ssh 통해 라이브 서버에서 다양한 테스트를 수행하고 짧은 코드를 작성해야합니다 . 말한 기능이 VIM 또는 다른 명령 행 편집기와 통합 될 수 있지만 대부분 큰 문제가있을 수 있습니다.

• 대부분의 IDE는 축소 코드 / 설명을 지원 하며 최종 결과는 다음과 같습니다.

  정상 대신 :

  

주석이 필요하지 않은 경우 코드를 더 읽기 쉽게 만드십시오.

소스 코드 및 문서화 방법

http://jasmine.github.io/2.3/introduction.html