Best line-by-line code explanation prompt I found so far

OpenAI Codex
1

I tried quite a few code explanation prompts - sharing this one I found recently, it works way better than anything I tried before:

We have the following [xxx] code:

```[xxx]
	<your code here>
        <many lines of it>
\```

Let's explain what it does line by line:

```[xxx]

(remove the backslash before the closing ``` - I had to put it or it breaks the formatting of this post)

This produced by far the most detailed and easy to understand outputs I ever had. I think it works particularly well because it emulates the style of tutorial/blog posts/readme’s in markdown, and thus the model replicates the easy to understand and detailed language they use. I used it on some ancient fortran code from an obscure scientific paper and the amount of details and contextual information it gives is mind blowing:

We have the following fortran code:

	common /fun/ pr(35),ob(35)
	real d(35,82)
	external funk,pp
	call sas('82.dat','82m1.lst','82m1.fit')
	write(7,"(' *** 82Ss - model 1: FLMP ***')")
	read(9,"(5f8.5)")d
	call runstp(funk,10,35,82,d,ob,pr,pp)
	stop
	end

	subroutine funk
	common /step/ nv,ntrace,matrix,chisq,mask(100),x(100)
	common /fun/ pr(35),ob(35)
c               a v     a     v
	real bi(5,5),au(5),vi(5)
	equivalence (pr(1),bi),(pr(26),au),(pr(31),vi)
	integer a,v
	real xv(5),xa(5),ntop
	equivalence (x(1),xv),(x(6),xa)

	do 40 v=1,5
40	  vi(v)=xv(v)

	do 50 a=1,5
50	  au(a)=xa(a)

	do 60 v=1,5
	do 60 a=1,5
	   top=xv(v)*xa(a)
	   ntop=(1.-xv(v))*(1.-xa(a))
60	   bi(a,v)=top/(top+ntop)
	call cchi(ob,pr,35)
	return
	entry pp(is,rmsd)
	write(7,117)is,rmsd,xv,xa
117	format(/' Sub  'i2' rms= 'f7.4/' v  = '5f7.4/' a  = '5f7.4)
	return
	end

Let’s explain what it does line by line:

	common /fun/ pr(35),ob(35)

This is the common block that contains the observed and predicted values.

	real d(35,82)

This is the data array. It is a 35x82 array of real numbers. The first
dimension is the number of observed values, and the second dimension is the
number of predicted values. The first observed value is pr(1), the second
is pr(2), and so on. The first predicted value is ob(1), the second is
ob(2), and so on.

	external funk,pp

This is the external declaration of the funk and pp subroutines. These
are the subroutines that do the actual work of the program.

	call sas('82.dat','82m1.lst','82m1.fit')

This is the call to the SAS program. It reads the observed and predicted
values from the files 82.dat and 82m1.lst. The 82m1.fit file contains
the initial values for the parameters.

	write(7,"(' *** 82Ss - model 1: FLMP ***')")

This is a message to the SAS log.

	read(9,"(5f8.5)")d

This reads the data array from the SAS data file. The data file is
82m1.dat. The 5f8.5 means that each number is a real number with 5
digits, 8 of which are after the decimal point, and 5 digits after that.

	call runstp(funk,10,35,82,d,ob,pr,pp)

This is the call to the runstp subroutine. The funk subroutine is the
one that does the actual work of the program. The 10 is the number of
iterations. The 35 is the number of observed values. The 82 is the
number of predicted values. The d is the data array. The ob is the
observed values. The pr is the predicted values. The pp is the
parameter values.

24 Likes
2

Ooh! I was thinking about how to get this to teach me more! This’ll help! Thanks!

3

What’s the scientific paper?

4

None, I’m using it as a teaching to for me so I can learn to program.

2 Likes
5

This is really fascinating - what parameters were you using (temperature, top-p, etc.)? I’m working on a project that is documenting code in an automated manner, and it’s always neat to see new prompt designs!

1 Like
6

“We speak the right words. Then we create life itself… Out of chaos.” - Dr. Ford (Anthony Hopkins).

7

Hi @ldorigo , thanks for sharing your prompt.

I’m using a similar structure for getting code explanations. In my tests, I noticed that providing metadata like programming language name, helps Codex to deduce the programming language effectively. This is particularly useful is the code snippet is not long enough or the sample syntax is similar to other programming languages.

2 Likes