<div dir="auto"><div>Hi Joe,<div dir="auto"><br></div><div dir="auto">Thanks for sharing!</div><div dir="auto"><br></div><div dir="auto">I'm going to use your handout as a base for my numerical computing classes, (with an appropriate citation, of course :-)).</div><div dir="auto"><br></div><div dir="auto"><br></div><br><br><div class="gmail_quote"><div dir="ltr" class="gmail_attr">чт, 9 мая 2019 г., 21:19 Joe Harrington <<a href="mailto:jh@physics.ucf.edu">jh@physics.ucf.edu</a>>:<br></div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
  
    
  
  <div text="#000000" bgcolor="#FFFFFF">
    <p>I have a handout for my PHZ 3150 Introduction to Numerical
      Computing course that includes some rules:</p>
    <p>(a) All integer-valued floating-point numbers should have decimal
      points after them. For<br>
      example, if you have a time of 10 sec, do not use</p>
    <pre>y = np.e**10 # sec</pre>
    <p> use <br>
    </p>
    <pre>y = np.e**10. # sec</pre>
    <p> instead.  For example, an item count is always an integer, but a
      distance is always a float.  A decimal in the range (-1,1) must
      always have a zero before the decimal point, for readability:</p>
    <pre>x = 0.23 # Right!
</pre>
    <pre>x = .23 # WRONG
</pre>
    <p>The purpose of this one is simply to build the decimal-point
      habit.  In Python it's less of an issue now, but sometimes code is
      translated, and integer division is still out there.  For that
      reason, in other languages, it may be desirable to use a decimal
      point even for counts, unless integer division is wanted.  Make a
      comment whenever you intend integer division and the language uses
      the same symbol (/) for both kinds of division.<br>
    </p>
    <p>(b) Use spaces around binary operations and relations
      (=<>+-*/). Put a space after “,”.<br>
      Do not put space around “=” in keyword arguments, or around “ **
      ”.</p>
    <p>(c) Do not put plt.show() in your homework file! You may put it
      in a comment if you<br>
      like, but it is not necessary. Just save the plot. If you say<br>
    </p>
    <pre>plt.ion()</pre>
    <p>plots will automatically show while you are working.</p>
    <p>(d) Use:<br>
    </p>
    <pre>import matplotlib.pyplot as plt</pre>
    <p>NOT:<br>
    </p>
    <pre>import matplotlib.pylab as plt</pre>
    <p>(e) Keep lines to 80 characters, max, except in rare cases that
      are well justified, such as<br>
      very long strings. If you make comments on the same line as code,
      keep them short or<br>
      break them over more than a line:<br>
    </p>
    <pre>code = code2   # set code equal to code2

# Longer comment requiring much more space because
# I'm explaining something complicated.
code = code2

code = code2   # Another way to do a very long comment,
               # like this one, which runs over more than
               # one line.
</pre>
    <p>(f) Keep blocks of similar lines internally lined up on decimals,
      comments, and = signs.  This makes them easier to read and
      verify.  There will be some cases when this is impractical.  Use
      your judgment (you're not a computer, you control the computer!):<br>
    </p>
    <pre>x    =   1.      # this is a comment
y    = 378.2345  # here's another
fred = chuck     # note how the decimals, = signs, and
                 # comments line up nicely...
alacazamshmazooboloid = 2721 # but not always!
</pre>
    <p>(g) Put the units and sources of all values in comments:</p>
    <pre>t_planet = 523.     # K, Smith and Jones (2016, ApJ 234, 22)
</pre>
    <p>(h) I don't mean to start a religious war, but I emphasize the
      alignment of similar adjacent code lines to make differences pop
      out and reduce the likelihood of bugs.  For example, it is much
      easier to verify the correctness of:<br>
    </p>
    <pre>a     = 3 * x + 3 * 8. *     short    - 5. * np.exp(np.pi * omega * t)
a_alt = 3 * x + 3 * 8. * anotshortvar - 5. * np.exp(np.pi * omega * t)
</pre>
    <p>than:<br>
    </p>
    <pre>a = 3 * x + 3 * 8. * short - 5. * np.exp(np.pi * omega * t)
a_altvarname = 3 * x + 3*9*anotshortvar - 5. * np.exp(np.pi * omega * i)
</pre>
    <p>(i) Assign values to meaningful variables, and use them in
      formulae and functions:</p>
    <pre>ny = 512
nx = 512
image = np.zeros((ny, nx))
expr1 = ny * 3
expr2 = nx * 4
</pre>
    <p>Otherwise, later on when you upgrade to 2560x1440 arrays, you
      won't know which of the 512s are in the x direction and which are
      in the y direction.  Or, the student you (now a senior researcher)
      assign to code the upgrade won't!  Also, it reduces bugs arising
      from the order of arguments to functions if the args have
      meaningful names.  This is not to say that you should assign all
      numbers to functions.  This is fine:<br>
    </p>
    <p>circ = 2 * np.pi * r<br>
    </p>
    <p>(j) All functions assigned for grading must have full docstrings
      in numpy's format, as well as internal comments.  Utility
      functions not requested in the assignment and that the user will
      never see can have reduced docstrings if the functions are simple
      and obvious, but at least give the one-line summary.</p>
    <p>(k) If you modify an existing function, you must either make a
      Git entry or, if it is not under revision control, include a
      Revision History section in your docstring and record your name,
      the date, the version number, your email, and the nature of the
      change you made.</p>
    <p>(l) Choose variable names that are meaningful and consistent in
      style.  Document your style either at the head of a module or in a
      separate text file for the project.  For example, if you use
      CamelCaps with initial capital, say that.  If you reserve initial
      capitals for classes, say that.  If you use underscores for
      variable subscripts and camelCaps for the base variables, say
      that.  If you accept some other style and build on that, say
      that.  There are too many good reasons to have such styles for
      only one to be the community standard.  If certain kinds of values
      should get the same variable or base variable, such as fundamental
      constants or things like amplitudes, say that.<br>
    </p>
    <p>(j) It's best if variables that will appear in formulae are
      short, so more terms can fit in one 80 character line.<br>
    </p>
    <p>Overall, having and following a style makes code easier to read. 
      And, as an added bonus, if you take care to be consistent, you
      will write slower, view your code more times, and catch more bugs
      as you write them.  Thus, for codes of any significant size,
      writing pedantically commented and aligned code is almost always
      faster than blast coding, if you include debugging time.</p>
    <p>Did you catch both bugs in item h?<br>
    </p>
    <p>--jh--<br>
    </p>
    <pre></pre>
    <div class="m_-7325228443087328228moz-cite-prefix">On 5/9/19 11:25 AM, Chris Barker - NOAA
      Federal <a class="m_-7325228443087328228moz-txt-link-rfc2396E" href="mailto:chris.barker@noaa.gov" target="_blank" rel="noreferrer"><chris.barker@noaa.gov></a> wrote:</div>
    <blockquote type="cite">
      <div class="m_-7325228443087328228moz-text-html" lang="x-unicode">
        <div dir="ltr">Do any of you know of a style guide for
          computational / numpy code?</div>
        <div dir="ltr"><br>
        </div>
        <div dir="ltr">I don't mean code that will go into numpy itself,
          but rather, users code that uses numpy (and scipy, and...)</div>
        <div dir="ltr"><br>
        </div>
        <div dir="ltr">I know about (am a proponent of) PEP8, but it
          doesn’t address the unique needs of scientific programming.</div>
        <div dir="ltr"><br>
        </div>
        <div dir="ltr">This is mostly about variable names. In
          scientific code, we often want:</div>
        <div dir="ltr"><br>
        </div>
        <div dir="ltr">- variable names that match the math notation- so
          single character names, maybe upper or lower case to mean
          different things ( in ocean wave mechanics, often “h” is the
          water depth, and “H” is the wave height)</div>
        <div dir="ltr"><br>
        </div>
        <div dir="ltr">-to distinguish between scalar, vector, and
          matrix values — often UpperCase means an array or matrix, for
          instance.</div>
        <div dir="ltr"><br>
        </div>
        <div dir="ltr">But despite (or because of) these unique needs, a
          style guide would be really helpful.</div>
        <div dir="ltr"><br>
        </div>
        <div dir="ltr">Anyone have one? Or even any notes on what you do
          yourself?</div>
        <div dir="ltr"><br>
        </div>
        <div dir="ltr">Thanks,</div>
        <div dir="ltr">-CHB</div>
        <div dir="ltr"><br>
        </div>
        <div dir="ltr"><br>
        </div>
        <div dir="ltr"><br>
        </div>
        <div dir="ltr"><br>
        </div>
        <blockquote type="cite">
          <div dir="ltr">
            <div dir="ltr">
              <div>-- <br>
                <div dir="ltr" class="m_-7325228443087328228gmail_signature" data-smartmail="gmail_signature"><br>
                  Christopher Barker, Ph.D.<br>
                  Oceanographer<br>
                  <br>
                  Emergency Response Division<br>
                  NOAA/NOS/OR&R            (206) 526-6959   voice<br>
                  7600 Sand Point Way NE   (206) 526-6329   fax<br>
                  Seattle, WA  98115       (206) 526-6317   main
                  reception<br>
                  <br>
                  <a href="mailto:Chris.Barker@noaa.gov" target="_blank" rel="noreferrer">Chris.Barker@noaa.gov</a></div>
              </div>
            </div>
          </div>
        </blockquote>
      </div>
    </blockquote>
  </div>

_______________________________________________<br>
NumPy-Discussion mailing list<br>
<a href="mailto:NumPy-Discussion@python.org" target="_blank" rel="noreferrer">NumPy-Discussion@python.org</a><br>
<a href="https://mail.python.org/mailman/listinfo/numpy-discussion" rel="noreferrer noreferrer" target="_blank">https://mail.python.org/mailman/listinfo/numpy-discussion</a><br>
</blockquote></div></div></div>