10
\$\begingroup\$

Suppose I have a project that is written in a literate format (e.g., emacs org-mode), and I would like to have that code reviewed. What is the preferred way to post the code?

Some options that come immediately to mind are:

  • Preserve the literate form of the program. It depends on the project, but there's likely to be quite a bit of prose surrounding the actual code. Even very small libraries may be relatively long when expressed in literate form. This makes the code clear, but is not necessarily concise.
  • Post the extracted code. This keeps the post short, but is not necessarily clear.
  • Post the extracted code, possibly including select portions of the prose, and link to the full literate version -- preferably a specific version under revision control.

However, I'm sure there are other options that are worth considering as well.

Also, it could very well be the case that there is no single approach that fits in all situations. If that's the case, what are some heuristics for choosing the right approach?

\$\endgroup\$

2 Answers 2

Reset to default
13
\$\begingroup\$

Code Review wants to see your code in context. In general, you should post the "real" code in the state that you normally work with. If it's literate code, then post it as literate code. To get the best value out of Code Review, avoid sanitizing your code just for the sake of posting a question.

\$\endgroup\$
3
  • \$\begingroup\$ We're not worried about "post-processing" on your code, only about what you are directly dealing with. \$\endgroup\$
    – Der Kommissar
    Dec 7, 2016 at 6:49
  • \$\begingroup\$ Could you clarify whether you mean I should post the raw markup or a rendered form of the document? \$\endgroup\$
    – Nathan Davis
    Dec 9, 2016 at 17:42
  • \$\begingroup\$ I think that @Quuxplusone has the right idea. Whatever format you normally use to work with the code is the most important. I assume that that would be the raw markup. The rendered form could be helpful as well, but would be of secondary importance. \$\endgroup\$
    – 200_success
    Dec 9, 2016 at 17:49
6
\$\begingroup\$

If I were going to post some WEB or CWEB code for review, I would definitely post the raw source code, but I would also provide a link to download the "woven" (PDF) version, because that's the "presentation" format — it's not the code, but it is the code's output/behavior, which is fair game for reviewers to comment on, if it's suboptimal in some way. Compare what the best answers on TeX SE do: post the code, but also post the output.

I would not post, nor link to, the "tangled" (compiled) code, any more than I'd post the assembly output of a C++ program I wanted reviewed.

The very small library you linked to is a bit of a special case, I would hope, in that it's not really "literate code" so much as "plain old code, but archived in a special non-compressed format where each file must be preceded by a header describing (in English) how trivial this particular next file is." :) Still, if you're posting it on CodeReview, I think the raw source code is the most relevant format, because that's the format that's going to be edited, grepped, and generally software-engineered.

In general, I suspect literate code doesn't make for good CodeReview questions, just because of how big and tangly literate programs ironically tend to be. Maybe this is because I've only ever seen Knuth do it, but I've never seen a program where I felt like could pluck a page out of the middle of the program and understand or "code-review" it in isolation, any more than you could "book-review" a page out of the middle of somebody's novel. But — I'm looking forward to being proved wrong!

\$\endgroup\$
6
  • \$\begingroup\$ Thanks for your thoughtful reply. If I understand correctly, you advocate posting the raw markup, as opposed to presenting the document in a rendered form. Isn't that akin to including raw documentation files in your post? \$\endgroup\$
    – Nathan Davis
    Dec 9, 2016 at 6:14
  • \$\begingroup\$ Yep. CodeReview is for the review of code, that is, text written by engineers and readable by both computers and other engineers. If you hide the code you've actually written, and instead post only the rendered output of the compiler... well... that's not very useful in this context. \$\endgroup\$
    – Quuxplusone
    Dec 9, 2016 at 7:05
  • \$\begingroup\$ Well, the tangled code should certainly be readable by engineers. I understand your point about it not technically being the code in the way it's originally expressed. But your analogy with object code just doesn't ring true to me. A literate program is simply a document that just happens to have some code embedded in it. Isn't it the code that is the center of the review, rather than the markup that used to express it? \$\endgroup\$
    – Nathan Davis
    Dec 9, 2016 at 17:35
  • \$\begingroup\$ @NathanDavis: "the tangled code should certainly be readable by engineers" — Well, I'd say that machine code should also be readable by certain types of engineers, at least with some pain. But that's not what we mean when we say "is this code readable". Here's an example of a tangled CWEB program — it's kind of like trying to read the output of gcc -E. I stand by my answer: engineers write (and review) source code, not compiled output. \$\endgroup\$
    – Quuxplusone
    Dec 12, 2016 at 3:23
  • \$\begingroup\$ All I can say is that with the literate programs I have written, the tangled code is formatted in pretty much exactly the same as if I'd written the code by hand. But that's not really my main point (tangled vs. untangled). To me, the more pertinent question is: rendered document or raw markup. If I'm not mistaken, you advocate posting the raw markup. But like I said before -- it's the code that's centric, not the raw markup. Any thoughts / counter-points in that regard? \$\endgroup\$
    – Nathan Davis
    Dec 12, 2016 at 4:26
  • \$\begingroup\$ @NathanDavis: I think we're talking past each other. I'll try one more time, but I believe I'm just repeating myself. "If you ask me to review your CUDA code, I'll want to see the code, not the rendered output. If you ask me to review your HTML code, I'll want to see the code, not the rendered output. If you ask me to review your TeX code, I'll want to see the code, not the rendered output. If you ask me to review your CWEB code, I'll want to see the code, not the rendered output." If you never review their source code, then how will the questioner ever learn to write good source code? \$\endgroup\$
    – Quuxplusone
    Dec 12, 2016 at 19:32

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .