2

What is the best way to comment a long Module?

For linear flowing calculations that need not be organised in modules, I usually mix text and math. But how can I do that inside a module, or block, or any other scoping construct?

m_goldberg
  • 107,779
  • 16
  • 103
  • 257
yarchik
  • 18,202
  • 2
  • 28
  • 66
  • 1
    (* like this *). – J. M.'s missing motivation Jul 14 '15 at 12:11
  • Don't let your modules get that long. Split them into subfunctions and comment/document those. – Mr.Wizard Jul 14 '15 at 12:36
  • Probably suggestions of @"Guess who it is" and @Mr.Wizard is the only valid way in spirit of functional programming. However, it is so hard... Subfunctions are getting too specialized. – yarchik Jul 14 '15 at 12:43
  • Even if a subfunction is only used once I do not think it hinders readability. If the goal is clear documentation I think this is acceptable. But it is difficult to discuss matters of style without some example. Perhaps an existing post on this site could serve that purpose? – Mr.Wizard Jul 14 '15 at 12:46
  • 2
    By the way I use (* inline comments *) a fair bit and I am not sure I understand your complaint about "convenience and look." For an sample of my style, though it changes from time to time, please see: Optimal Code Layout in Mathematica? – Mr.Wizard Jul 14 '15 at 12:52
  • 1
    @Mr.Wizard I was trying to find an existing post on this site for illustration. Perhaps one answer of Guess who it is can be used as an example http://mathematica.stackexchange.com/questions/39733/how-to-plot-ternary-density-plots If text could be added here and there the module would be much more legible. – yarchik Jul 14 '15 at 12:59
  • @yarchik, ah, a work in progress… so many ideas, so little computer time. :) I really should update that with new ideas when I get the chance… – J. M.'s missing motivation Jul 14 '15 at 13:22

1 Answers1

2

Not sure it's good practice, but in a notebook you can format the text inside the (* *) comment designators to your liking. Here's an example module with "Text" style used with inline comments:

enter image description here

Additionally, it's possible to disable evaluation for individual cells (from the menu: "Cell"-->"Cell Properties"-->"Evaluatable"), and one can use Inactive to prevent evaluation of whole blocks or modules.

Also, as @Mr.Wizard mentioned in his comment, it is often better practice to refactor your modules into more manageable pieces--subfunctions that work together. These smaller pieces are easier to document with explanatory text and divisions in the notebook interface, and short inline comments.

dionys
  • 4,321
  • 1
  • 19
  • 46