อะไรจะเป็นวิธีที่ดีที่สุดในการเขียนโค้ดสำหรับกระดาษเพื่อให้ผู้อ่านสามารถจับคู่ผลลัพธ์กับโค้ดที่สร้างได้อย่างชัดเจน?

ฉันกำลังเขียนกระดาษที่ทำซ้ำได้และกระดาษนั้นมีผลการคำนวณที่สร้างโดยสคริปต์ Python (สคริปต์ MATLAB ที่คล้ายกันสร้างผลลัพธ์ที่เหมือนกันเกือบทั้งหมด) ฉันรู้สึกว่ากระดาษจะง่ายต่อการเข้าใจสำหรับผู้อ่านหากพวกเขาสามารถจับคู่การคำนวณในกระดาษกับการคำนวณในรหัส งานนำเสนอแบบแผนเชิงนามธรรมและตัวอย่างในกระดาษควรทำให้พิธีการนี้เป็นรูปธรรมมากขึ้นสำหรับผู้อ่าน (หลายคนจะเป็นวิศวกร) รหัสอาจเป็นบันทึกที่มีรายละเอียดมากที่สุดเกี่ยวกับวิธีการคำนวณและการทำให้ชัดเจนสามารถช่วยเราได้ในระหว่างกระบวนการตรวจสอบ

ไม่มีใครมีข้อเสนอแนะเกี่ยวกับวิธีการทำให้การติดต่อระหว่างรหัสและผลลัพธ์การคำนวณ (ตัวเลข, สมการ) ชัดเจนมากขึ้น?

ตัวอย่างเช่นฉันคิดว่าเมื่อมันมาถึงบรรทัดของโค้ดที่ใช้ขั้นตอนต่าง ๆ ในกระดาษฉันสามารถอ้างอิงหมายเลขสมการ (มันน่าอัศจรรย์ถ้าฉันสามารถอ้างอิงข้ามระหว่างรหัสและ LaTeX แต่การติดฉลากด้วยมือนั้นดี) และฉันสามารถเขียนฟังก์ชั่นที่สอดคล้องกับตัวอย่างและตัวเลขต่าง ๆ เช่น

def example_1():
    # Insert code corresponding to first example
    pass

def figure_1():
    # Insert code that generates Figure 1
    pass

หากรหัสมีขนาดใหญ่และฉันไม่ได้พยายามอธิบายว่าวิธีการทางคณิตศาสตร์ที่แตกต่างกันจำนวนมากที่ใช้ในงานวิศวกรรมนั้นเหมือนกันจริง ๆ ฉันอาจจะไม่รำคาญมากนักกับการทำให้รหัสชัดเจน แต่ให้ลักษณะนามธรรมของ กระดาษและฐานรหัสขนาดเล็กดูเหมือนว่าอาจมีค่าในแบบฝึกหัดนี้

1. คุณอาจลองเขียนบทความทั้งหมด Noweb การตั้งค่าค่อนข้างน่าเบื่อ แต่เป็นวิธีที่มีประสิทธิภาพมากในการผสมโค้ดและข้อความสมการและตัวเลขในรูปแบบ LaTeX สำหรับโปรแกรมที่มีความยาวก็จะทำให้โค้ดของคุณกลายเป็นหนังสือมากกว่าบทความ แต่สำหรับโปรแกรมสั้น ๆ มันอาจใช้งานได้ดี

2. หากคุณไม่ต้องการไปไกลขนาดนั้นคุณควรจัดรูปแบบส่วนความคิดเห็นของรายการรหัสของคุณโดยใช้ LaTeX listingsแพคเกจช่วยให้คุณสามารถดึงออกนี้ นี่เป็นตัวอย่างสั้น ๆ :

\ documentclass {บทความ}
\ usepackage {} amsmath
\ usepackage {} รายชื่อ
\ begin {เอกสาร}
\ begin {} สม
  \ ฉลาก {EQ: หนึ่ง}
  ขวาน = b
\ end {} สม
\ begin {lstlisting} [escapechar = \%]
  # ความคิดเห็นที่มีการอ้างอิงถึงสมการ% ~ \ eqref {eq: one}%
  def f (a):
    ส่งกลับ +1
\ end {} lstlisting
\ end {เอกสาร}

ด้วยการดัดแปลงเพิ่มเติมบางอย่างคุณควรจะสามารถรับหมายเลขสมการอ้างอิงของคุณให้ปรากฏในแบบอักษร monospace ที่ใช้สำหรับแสดงรายการสมการ

วิธี noweb ที่กล่าวถึงโดย Bill มีการพัฒนาค่อนข้างน้อยทั้งในจิตวิญญาณดั้งเดิมของการจัดทำรหัส (แทนที่จะตีพิมพ์ทางวิทยาศาสตร์) ภายใต้การเขียนโปรแกรมระยะความรู้และตอนนี้มาในหลาย ๆ รสชาติ (ฉันเดาว่า noweb ที่doxygenต่าง ๆ และรุ่นเฉพาะภาษาสามารถสร้างเอกสารในเท็กซ์, HTML, และรูปแบบอื่น

มากไปยังจุดของคุณ noweb ได้รับการพัฒนาบางครั้งในRชุมชน (แต่เดิมSชุมชนดังนั้นชื่อ) ภายใต้ชื่อ "Sweave" โดยมีเป้าหมายในการให้กระดาษ "ทำซ้ำการวิจัย" ซึ่งรหัสจะทำงานจริงเมื่อ ไฟล์ลาเท็กซ์ถูกรวบรวม (และแสดงทางเลือกเช่นกัน) มีบทความเชิงวิชาการจำนวนมากเขียนใน Sweave (รวมถึงฉันเชื่อว่าวารสาร R ทั้งหมด แต่ดูวารสารชีวสถิติและนโยบายเกี่ยวกับเอกสารที่ทำซ้ำได้)

ในขณะที่ Sweave ยังคงเป็นส่วนหนึ่งของการติดตั้งฐาน R แต่จะถูกแทนที่ด้วยknitrซึ่งตอนนี้ไม่เชื่อเรื่องภาษาทำให้เป็นทางเลือกที่เป็นไปได้สำหรับรหัสไพ ธ อนของคุณ Knitr รองรับการเขียนใน LaTeX หรือ markdown, รองรับการเน้นไวยากรณ์, การแคช, การทำให้เป็นภายนอกของโค้ดจากแหล่งลาเท็กซ์และคุณสมบัติอื่น ๆ ที่ต้องการสำหรับงานประเภทนี้

Python มีวิธีแก้ปัญหาของตัวเองที่คล้ายกันโน๊ตบุ๊ค ipythonซึ่งสามารถแสดงผลเป็น HTML อาจเป็น LaTeX แต่ฉันรู้เรื่องนี้น้อยลง

อีกหนึ่งโปรเจคที่ควรค่าแก่การดูคือdexyitซึ่งเป็นโปรแกรมสำหรับผู้ไม่เชื่อเรื่องภาษาซึ่งทำงานได้ดีกับ LaTeX และ HTML ในขณะที่มันมีตัวอย่างเพิ่มเติมในการบันทึกรหัสมากกว่าการเขียนบทความทางวิทยาศาสตร์การทำงานใน LaTeX มันควรจะตรงไปตรงมา

ทั้งสองknitrและdexyitจะทำสิ่งที่คุณอธิบายใน LaTeX อย่างแน่นอนรวมถึงการชี้ไปที่สคริปต์ไพ ธ อนภายนอกและการอ่านโค้ด สิ่งที่คล้ายกันสามารถทำได้ใน DocBook และ XML แม้ว่าฉันจะไม่คุ้นเคยกับวิธีการนี้

แพคเกจ LaTeX ทำออกมาให้เน้นไวยากรณ์ที่กว้างขวางมาก (ขึ้นอยู่กับ Pygments) และช่วยให้การอ้างอิงข้ามในทั้งสองทิศทาง คุณสามารถหลบหนีไปยัง LaTeX ได้จากภายในส่วนของโค้ด (ส่วนที่ทำออกมา) และคุณสามารถอ้างอิงในข้อความหลักของคุณไปยังบรรทัดของรหัส นอกจากนี้ยังมีสภาพแวดล้อมรายการเพื่อให้คุณสามารถสร้าง "รายการรายชื่อ" (เช่นรายการตาราง) และอนุญาตให้อ้างอิงรายการทั้งหมด ดู LaTeX MWE และผลลัพธ์ด้วย LuaLaTeX ด้านล่าง (อย่าตัดสินรหัส :-))

อีกทางเลือกหนึ่งคือใช้PythonTeXจากผู้แต่ง / ผู้ดูแลเดียวกันซึ่งอนุญาตให้เรียกใช้การคำนวณในขณะที่คอมไพล์แหล่ง LaTeX ด้วยเหตุนี้ผลลัพธ์ของกระดาษและรหัสจึงถูกสร้างขึ้นพร้อมกันเสมอ ดูแกลเลอรี่ PythonTeXที่นี่

\documentclass[a4paper,notitlepage,11pt]{article}

\usepackage{amsmath}
\usepackage{cases}
\usepackage{minted}

\begin{document}

The mathematical definition of the Fibonacci
series is given in~Equations~(\ref{eq:fibdef:init1}--\ref{eq:fibdef:rule})
It can be implemented using either a recursive or iterative algorithm
in Python.

\begin{numcases}{f(n)=}
  \label{eq:fibdef}
    0               & n = 0 \label{eq:fibdef:init1}\\
    1               & n = 1 \label{eq:fibdef:init2}\\
    f(n-1) + f(n-2) & \text{otherwise} \label{eq:fibdef:rule}
\end{numcases}

The algorithms below are an implementation of both variants.
Listing~\ref{alg:fib_recursive} shows the recursive variant (see
line~\ref{alg:fibo_rec:line_rec} in listing~\ref{alg:fib_recursive}) while
listing~\ref{alg:fib_iterative} shows the iterative variant. Both can be
optimized, of course.

\begin{listing}[ht]
  \begin{minted}[linenos, escapeinside=||]{python}
def fibo_rec(N):
    if N == 0:
        result = 1 |[Comment: See case (\ref{eq:fibdef:init1})]|
    elif N == 1:
        result = 1 |[Comment: See case (\ref{eq:fibdef:init2})]|
    else:
        result = fibo_rec(N-1) + fibo_rec(N-2) |\label{alg:fibo_rec:line_rec}[Comment: See case (\ref{eq:fibdef:rule})]|

    return result
  \end{minted}
\caption{Fibonacci recursive}
\label{alg:fib_recursive}
\end{listing}

\begin{listing}[ht]
  \begin{minted}[linenos, escapeinside=||]{python}
def fibo_iter(N):
    if N == 0:
        fib_N = 1
    elif N == 1:
        fib_N = 1
    else:
        fib_Nmin2 = 1
        fib_Nmin1 = 1
        for i in range(2,N+1):
            fib_N = fib_Nmin2 + fib_Nmin1
            fib_Nmin2 = fib_Nmin1
            fib_Nmin1 = fib_N
    return fib_N
  \end{minted}
\caption{Fibonacci iterative}
\label{alg:fib_iterative}
\end{listing}

\end{document}

ใช้การเขียนโปรแกรมการทำงานความรู้ด้านขององค์กรโหมด

ผู้ใช้โหมดองค์กรส่วนใหญ่มักจะมุ่งเน้นเฉพาะในฟังก์ชั่นการจัดการโครงการ / เวลาในตัวหรือความสามารถในการส่งออกเอกสารเป็นรูปแบบไฟล์ยอดนิยมหลายรูปแบบเช่นPDFจากง่ายต่อการดูแลไฟล์ข้อความ

อย่างไรก็ตามคุณลักษณะที่ดีที่สุดของโหมดองค์กรคือความสามารถในการสร้างโปรแกรมความรู้ในภาษาต่างๆมากกว่า 30 ภาษาพร้อมเพิ่มภาษาได้มากขึ้นทุกเดือนโดยชุมชนโอเพ่นซอร์ส

ด้านล่างเป็นตัวอย่างรหัสเล็กน้อยโดยใช้ Ruby และ Python:

 #+NAME: trivial-code-ex1
 #+BEGIN_SRC ruby 
   "hello world!"
 #+END_SRC

 #+RESULTS: trivial-code-ex1
 : hello world!


 #+NAME: func-of-x-and-y
 #+BEGIN_SRC python :var x=1 :var y=2 :session
   x + y
 #+END_SRC

 #+RESULTS: func-of-x-and-y
 : 3

ข้อดี

• รองรับภาษาการเขียนโปรแกรมมากกว่า30 ภาษารวมถึง R, Python, Ruby, Perl, C, C ++, Java, Clojure, Javascript, Lisp สามัญ, Shell, SQL, ...

• ความสามารถในการ:

  • จับ SRCผลลัพธ์บล็อกเป็นผลลัพธ์และ / หรือค่า
  • จัดรูปแบบ SRCผลลัพธ์บล็อกเป็นโค้ดรายการตารางลาเท็กซ์ html
  • ใช้ข้อมูลทั้งภายนอกและภายในสำหรับตัวแปรของSRCบล็อก
  • ใช้เอาต์พุตของSRCบล็อกที่มีชื่อเป็นSRCบล็อกเป็นตัวแปร
  • ใช้nowebไวยากรณ์ภายในSRCบล็อก

    เคล็ดลับ Pro:คุณสามารถใช้nowebไวยากรณ์เพื่อ:

    • แทรกรหัสจากSRCบล็อกชื่อเช่นfunc-of-x-and-yภายในSRCบล็อกอื่น

      #+BEGIN_SRC python :session :noweb yes 
        x=2
        y=3
        "f(x,y) is\n\n <<func-of-x-and-y>> \n\nso f({0},{1}) equals\n\n {2}".format(x,y,<<func-of-x-and-y>>)
      #+END_SRC
      
      #+RESULTS:
      : f(x,y) is
      : 
      :  x + y 
      : 
      : so f(2,3) equals
      : 
      :  5

    • แทรกผลลัพธ์ของSRCบล็อกที่มีชื่อเช่นfunc-of-x-and-yภายในSRCบล็อกอื่น

      #+BEGIN_SRC python :session :noweb yes 
        "f(x,y) is\n\n <<func-of-x-and-y>> \n\nso f(3,4) equals\n\n <<func-of-x-and-y(x=3,y=4)>>"
      #+END_SRC
      
      #+RESULTS:
      : f(x,y) is
      : 
      :  x + y 
      : 
      : so f(3,4) equals
      : 
      :  7

    • วางSRCบล็อกที่ตั้งชื่อไว้ที่ใดก็ได้ในไฟล์โหมดองค์กรเพื่อให้สามารถอ่านได้และใช้:tangleส่วนหัวหรือรหัสส่งออกเป็นไฟล์ต้นฉบับภายนอก

• โครงการโอเพนซอร์ส - ฟรีทั้งในเบียร์และอิสระในอิสระ

• รูปแบบไฟล์ข้อความใช้งานได้ดีกับซอฟต์แวร์ควบคุมเวอร์ชันเช่น git
• Ooodles คุณสมบัติอื่น ๆ ที่ฉันจะไม่เข้าไปเพราะคำตอบนี้ใช้เวลานาน

จุดด้อย

• จำเป็นต้องติดตั้งและกำหนดค่า gnu emacs เพื่อใช้โหมดองค์กร

  หมายเหตุ:ส่วนใหญ่ของคุณหยุดอ่านคำตอบนี้หลังจากที่คุณอ่าน gnu emacs สำหรับวิญญาณผู้กล้าหาญที่หลงเหลืออยู่คุณสามารถใช้เท็กซ์เอดิเตอร์ที่คุณชื่นชอบและเรียก emacs เพื่อประมวลผลไฟล์โหมดองค์กรของคุณจากบรรทัดคำสั่ง

• จำเป็นต้องติดตั้งและกำหนดค่าซอฟต์แวร์การเขียนโปรแกรมทั้งหมดที่คุณต้องการ

• จำเป็นต้องติดตั้งและกำหนดค่ายูทิลิตี้ LaTeX หากคุณต้องการสร้าง PDF
• โหมดองค์กรยังไม่เป็นที่รู้จักipython notebooksหรือSweaveอย่างนั้นคุณอาจไม่เห็นการโพสต์งานมากถึงแม้ว่าการเพิ่มความสามารถในการเขียนโปรแกรม Literate ในปี 2008
• การเรียนรู้ไวยากรณ์มาร์กอัปโหมดองค์กร
• อาจเรียนรู้วิธีใช้ gnu emacs หรือ spacemacs หากต้องการใช้ประโยชน์จากเครื่องมือสุดเจ๋งอื่น ๆ ที่ทำงานกับโหมด org

การเปิดเผยแบบเต็ม:ฉันเป็นผู้ดูแลหลักของแพ็คเกจ org-mode สำหรับตัวแก้ไข Atom

---

รหัสในคำตอบนี้ถูกตรวจสอบโดยใช้:
emacs เวอร์ชั่น: GNU Emacs 25.2.1 รุ่น
org-mode: 9.1.2