# Bad Code

If my task is to help you "speed up code", then I feel that the first
part is to help you maintain it.

This is one of the 10/90 principles of programming: 10% of the time
will be spent writing a program; 90% of the time will be spent
maintaining it.[^other]

Let's start by looking at a code fragment. For the sake of argument,
assume that it "works," in the sense that it's part of a larger
program that produces the results that you expect.

Pick the Python version or the C++ version. Can you figure out what,
in my opinion, is wrong with this code?

:::{code-block} python
:name: bad-python-code
:caption: What's wrong with this Python code?
# Compute the vector product of the two velocities
i = 10
while j < i+1:
    k = i + 3
    s[j] = s[j] + k*j
    j = j + 1
:::

:::{code-block} c++
:name: bad-c-code
:caption: What's wrong with this C++ code?
// Compute the vector product of the two velocities
int i = 10;
while (j < i+1) {
    int k = i + 3
    s[j] = s[j] + k*j
    j = j + 1
}
:::

:::{hint}
In my opinion:

   - There are at two execution-speed problems with this code (though
     they affect the Python version more than the C++ version). There
     is also a separate speed problem with only the Python code.

   - There are also at least two programming-style problems with the
     above code.
:::

My answers are in the next section.

:::{admonition} Is this worth it?
:class: note

It's natural to ask this question. We're all busy. If the code works,
why make a fuss about it?

I offer the following in response:

   - If code is unclear, it will be harder to maintain. You may feel
     that's the next person's problem. Except that the next person is
     likely to be you! 

     Suppose you've have a program that performs a cluster-finding
     algorithm. It works, but it's quickly and sloppily written. You
     save it and move on to your next project.

     Six months later, your team comes back to you: "You're the
     cluster-finding expert. Update your code so that it accommodates
     this revision." Of course, you've forgotten about your old
     code.[^remember] You look at it now... and realize that five seconds
     worth of effort back then would have saved you hours or days
     re-analyzing your old code to figure out what it did.


   - Typically, physics groups don't do code review. But professional
     programming environments do. 

     A "code review" is when a group of
     programmers looks over your code to see if it's acceptable to add
     to a project, in much the same way a physics group will review a
     paper to see if it's acceptable for publication. If you find
     yourself in a programming group, they're not going to accept your
     code if has the kinds of flaws I discuss here.


   - When looking at code, physicists tend to treat it as a 
     "black box":[^black] They assume it just works, and use it as-is without
     thinking or even understanding what it does.

     Maybe this sounds fine, but put it in the context of
     quickly-written, sloppy, or slow code. In 2021, I wrote a
     quick-and-dirty bit of analysis code to answer a single
     question. In 2022, students copied that code, treated it as
     "perfect"[^reason] and used it in a loop to analyze 150 times
     more events than I did in my brief study. Result: Their analysis code
     ran slowly, because I hadn't put in the time to write proper
     code.

:::

:::{figure-md} code_quality_3-fig
:align: center

<img src="https://imgs.xkcd.com/comics/code_quality_3.png" alt="xkcd code_quality_3" width="100%">

<https://xkcd.com/1833/> by Randall Munroe
:::

[^other]: The other 10/90 principle is that 10% of the code is
    responsible for 90% of a program's execution time. We'll deal with
    creating faster code in the next section. 

[^remember]: I know you think you'll remember. You won't. Although
    arguments from authority are always suspect, please take it from
    someone who's been programming for over five decades.

[^black]: In this discussion, when I say "physicists like to put
    things in a black box," it's not exclusive. Other fields of study
    also tend to put things in a black box. However, since I mostly
    hang out with physicists and not pharmacists or airline pilots,
    I'll only speak for the folks I know.

[^reason]: For some reason they thought that, because I had written
    it, my code was superior to anything they could write. I can't
    begin to tell you how false that reasoning is.