태그 보관물: documentation

documentation

코드에서 수학적 논리 문서화 바람직하게는 코드 자체의 논리를 설명하는보다 효율적이고 이해하기

가끔은 아니지만 종종 코드에 수학 논리를 포함시켜야합니다. 사용되는 개념은 대부분 매우 간단하지만 결과 코드는 목적이 불분명 한 많은 변수가 아니며 의도하지 않은 일부 작업은 아닙니다. 코드를 읽을 수 없거나 유지할 수 없다는 것을 의미하는 것은 아니며 실제 수학 문제보다 이해하기가 어렵다는 것을 의미합니다. 이해하기 어려운 부분에 대해서는 언급하려고 노력하지만, 코드를 작성하는 것과 같은 문제가 있습니다. 텍스트에는 수학의 표현력이 없습니다 .

복잡한 코드의 일부, 바람직하게는 코드 자체의 논리를 설명하는보다 효율적이고 이해하기 쉬운 방법을 찾고 있습니다. TeX를 고려했습니다-문서를 작성하고 코드와 별도로 생성합니다. 그러나 TeX를 배워야하며 설명서 자체는 코드 자체가 아닙니다. 내가 생각한 또 다른 것은 종이 / 화이트 보드에 쓰여진 수학 표기법, 방정식 및 다이어그램을 찍고 javadoc에 포함시키는 것입니다.

더 간단하고 명확한 방법이 있습니까?


(설명 적 이름주기 PS timeOfFirstEvent대신을 t1변수로는) 실제로 더 자세한 심지어 더 열심히도 읽을 수있는 코드를합니다.



답변

그러한 상황에서해야 할 올바른 것은 알고리즘, 수식 또는 프로그래밍 언어가 허용하는 한 기본 실제 소스 와 정확히 동일한 변수 이름을 가진 것을 구현하고 그 위에 간결한 의견을 말하는 것입니다. 인용은 쉽게 접근 할 수있는 수학 설명과 연결되는 “[Knuth1968]에 설명 된 것과 같은 Levenshtein 거리 계산”과 같은 것입니다.

(당신이하지 않으면 같은 기준을하지만 수학은 어쩌면 당신은 스스로를 게시 고려해야한다, 사운드 및 유용하다. 그냥 선생님 ‘.)


답변

그런 알고리즘을 구현해야 할 때 몇 가지 일이 있습니다.

  1. 가능한 한 알고리즘을 자체 메소드 또는 바람직하게는 클래스로 분리하십시오. 현재 프로젝트에는 Math복잡한 알고리즘을 추가 하는 자체 클래스가 있습니다.

  2. 일반적인 약어 또는 용어에 대한 속기 참조를 포함하여 알고리즘이 일반 용어로 수행해야하는 작업을 요약합니다. 메서드 자체 에서이 작업을 수행하므로 코드와 함께 작동합니다.

  3. 기술 / 수학적 용어로 알고리즘 요약을 제공하고 내가 알고있는 외부 참조를 포함하십시오. 다시 말하지만, 메소드 자체 로이 작업을 수행하므로 관련성을 유지할 가능성이 높아집니다. 이 경우에는 평범한 텍스트가 좋지 않으므로 수학 용어를 최대한 인용하고 그 옆에 괄호로 설명합니다. 예를 들어 x^y (x raised to the power y)

  4. 알고리즘을 구성 요소로 분리하는 방법을 문서화하고 알고리즘에서 각 변수가 나타내는 것을 표시하십시오. 예.t1 is time of first event

  5. 알고리즘을 코딩하고 복잡한 부분을 주석 처리하십시오. 본질적으로 알고리즘 자체 내에서 명확하지 않거나 간단하지 않은 단계를 취하는 모든 곳에 주석을 추가합니다. 특히 명확하지 않은 지름길을 언급하고 구현 내에서 가져갈 수있는 이유는 무엇입니까?

  6. 알고리즘 작동을 확인하는 단위 테스트를 작성하십시오.

마지막으로, 그것이 정말로, 정말로, 정말로 복잡하다면, 나는 그 프로젝트에서 남은 시간 동안 그 코드를 소유하고 있다는 사실에 저를 사임합니다.

다른 사람이 코드를 이해하기 위해 외부 문서에 의존하는 것을 좋아하지 않습니다. 그렇습니다. 간결한 세부 사항을 얻을 때 특히 필요할 수 있습니다. 그러나 가능할 때마다 코드 자체에 모든 것을 유지하려고 노력하므로 업데이트되고 쉽게 찾을 수 있습니다. 이 경우, 나는 문서의 표현력보다는 정보에 대한 접근성을 중요하게 생각합니다.


답변

양적 금융 경제학 연구를 중심으로 진행되는 프로젝트에서 우리는 많은 수학을 활용하며 이미 게시 된 내용의 조합을 따릅니다.

  1. 사용중인 기본 소스에 대한 링크를 제공하십시오. 우리에게 가장 쉬운 방법은 BibTex-handle을 사용하는 것입니다. BibTex-handle은 기본적으로 모든 사람이 볼 수있는 종이의 ID입니다. 특정 소스에 따라 정기적으로 방정식 참조를 추가합니다.

  2. 모든 변수에 대한 설명을 제공하십시오. 우리는 원래의 논문이 그리스어 나 다른 문자를 사용한다면 Tex를 사용합니다. 그 이유는 종종 충분한 논문과 서적이 다른 표기법을 사용하기 때문입니다. 누군가가 수학을 재 작업해야하는 경우 훨씬 쉬워집니다.

  3. 방정식을 한 조각으로 코딩하십시오. 그렇게 인식하는 것이 훨씬 쉽습니다. 전체 방정식의 Tex-Code를 코드에 게시하지 마십시오. 방정식이 매우 짧고 tex 게시가 복잡하고 불필요하거나 수식이 거대하고 tex 코드가 컴파일되지 않는 한 tex 코드는 쓸모가 없습니다 ( 대신 참조). 방정식을 작은 조각으로 분해하면 무슨 일이 일어나고 있는지 이해하기가 어렵습니다 (적어도 수학에 능숙하다면).

IMHO의 가장 중요한 실현은 수식이 종종 상황에 따라 달라진다는 것입니다. 내가 아는 모든 수학 논문은 모델의 환경을 설정하는 데 시간이 걸립니다. 당신도 똑같이해야합니다.


답변

텍스트에는 수학의 표현력이 없습니다

네 말이 맞아 이미 코드 외부에서 수행 할 수있는 방법을 찾고 있으며 Tex는 가파른 학습 곡선 외에도 과도한 노력이므로 권장 사항은 다음과 같습니다.

OpenOffice.org/LibreOffice Math Equation Editor를 사용하십시오.

무료입니다. 열려 있습니다.

시각적으로 사용하거나 특수 언어로 방정식을 작성할 수 있습니다.

GUI를 사용할 때 “코드”가 표시되도록 패널에 생성되므로 언어를 즉시 배울 필요가 없습니다.

상단 패널에서 팔레트를 사용하여 방정식을 “그릴”수 있습니다. 하단 패널에서 동등한 표기법이 생성됩니다. 표기법을 파악하고 하단 패널에 표기법을 쓰고 상단 패널에 그래픽 출력을 표시하면 다른 방법으로 할 수 있습니다.


답변