Notebook formatting - easier descriptions for equations and results?

Question

When I do computations in mathematica, I generally try to make it readable for myself-in-the-future. This can be a cumbersome task in mathematica, where it often requires me to switch betwee a text cell, then back to an equation cell (or two), over and over again, to be able to label what a given equation/result is.

e.g.

(text:) This is the equation for ... .... ...
In[517]:= 2 + 2
Out[517]= 4

over and over again. Is there anyway to make mathematica produce output like the following?

In[517]:= 2 + 2  This is the ... Equation
Out[517]= 4      The resulting value ...

Answer 1

An interesting problem.

Trivially one could use Print like this:

Print[2 + 2, Spacer[50], "this is a note"]

4      this is a note

But that is hardly a usable syntax. Looking deeper into the system one observes that (* comments *) are stripped during parsing so those are out of reach without prohibitive contortions. Strings however are inert objects that could serve as comments. I propose this:

Version 2

$note = Null;

$PreRead =
  Replace[#,
    RowBox[{body__, ";", note_String?(StringMatchQ[#, "\"*\""] &)}] :>
     ($note = Style[ToExpression@note, Italic, Red]; RowBox[{body}])
  ] &;

$PrePrint = 
  If[$note =!= Null,
     # &[Row[{Pane@#, Spacer[50], $note}], $note = Null],
     #
  ] &;

(This code uses a new Global` symbol $note -- in practice it may be better to place this in a different context to prevent collisions and allow for e.g. ClearAll["Global`*"] without issue.)

Comments are made as Strings ending a line and following semicolon.

This has at least the limitation of the way that Mathematica reflows text in standard Input cells. Here the last comment, "Graphics", wraps to the next line:

When using this implement it may be preferable to use a cell style that does not reflow, such as Code:

Pane in the $PrePrint function is to handle a case such as the last line above; without it Graphics objects are incorrectly downsized.

Note that in version 2, because labeling is handled with $PrePrint, the functionality of Out remains intact allowing %^2 in the example and maintaining Output cell labels.

Answer 2

The best I can think of gets a bit cumbersome, but if you did everything this way one could deal with it consistently:

In[517]:= {2 + 2, "The resulting value ...'} (* This is the ... Equation *)

Out[517]= {4, The resulting value ...}

In[518]:= %[[1]] (* To use just the value *)

Out[518]= 4

Again quite cumbersome.