Welcome to the MUDE textbook. This is where assigned reading is located, along with interactive exercises to practice and study the module material.
_this is where stuff will be written later_
Content in this textbook will be added throughout the semester, and changes will be announced and documented as needed. When new content is added, it will be done in large chunks. Changes will not be made retroactively that impact the scope of the exams (in other words, you will never need to re-study material because it changed prior to the exam). Notifications of errors, corrections and suggestions for improvement are glady welcomed via the Answers platform and/or via the MUDE email address.
```{admonition}Interactive Pages: Use Python in your Browser!
This online textbook has a number of pages that are set up to be used interactively. On such pages you can use the "Live Code" button under the Rocket Ship icon in the top right to activate the interactive features and use Python interactively!
Sometimes the interactivity will involve completing an exercise, wheras on other pages it might simply provide the opportunity to edit the contents of code cells and execute it to explore the page contents interactively. Other pages may provide interactive figures (e.g., widgets).
This is a new feature that we are actively working to incorporate in the MUDE textbook, so please provide us feedback via the [Answers platform](https://answers.citg.tudelft.nl/) if things go well or you have suggestions for improvement.
"We focused on illustrating good programming practices in a format and language that is approachable to engineers with a varied programming background. As such, specific fundamental programming and computer science concepts are avoided. If you would like to learn more about theses concepts, specifically related to Python, the textbook by Guttag (2021) is an excellent reference.\n",
"This notebook is meant to be used interactively. Use the \"Live Code\" button under the Rocket Ship icon in the top right to activate the page and use Python interactively!\n",
"Whether you are a student, teacher or practitioner, we encourage you to [refer back to this document](https://mude.citg.tudelft.nl/book/programming/golden_rules.html) often and feel free to download it as a `*.ipynb` file to share. We expect to periodically update this document and perhaps share other topics in the 'Golden Rules' series. \n",
"\n",
...
...
%% Cell type:markdown id:6c618b60 tags:
(programming-gr)=
# The Golden Rules
The Golden Rules are a (simple!) set of guildelines to help you build good habits into your programming routines.
%% Cell type:markdown id:9c81abf5 tags:
**Why do the Golden Rules for Documentation and Communication exist?**
You will spend a lot of your study hours in the MUDE module writing, reading and debugging Python code, regardless of your prior programming experience. Your time is valuable, especially once you start working after graduation! Yet it is all too common that most code is never re-used because it is poorly *documented*, making it not understandable to others, or even to yourself at a later moment. In addition, as a young practicing engineer or researcher it is critical that you are able to use your code to effectively *communicate* your results, otherwise the effort put into your analysis is wasted. Good code writing, code documentation and presentation of results such as figures, tables and numbers are all essential for effective collaboration. Even when working individually, it is important to preserve your work such that you can easily understand and re-use in the future. This document will provide and explain a number of reccommendations to help you accomplish that.
The following quote summarizes the philosophy of this document concisely:
<divstyle="text-align: right"><em>Any fool can write code that a computer can understand. Good programmers write code that humans can understand.</em></div>
<divstyle="text-align: right"><em> ― Martin Fowler </em></div>
**A note of Encouragement**
This document contains a lot of information that might not appear to be useful to you...*yet*. Keep in mind that the content here was created in collaboration with many colleagues who are working in industry and will be looking to hire you after you graduate from TU Delft: they will appreciate good coding documentation and communication skills! Our primary advice in MUDE, and for the rest of your MSc program, is that you take a look at this material now, but also keep the Golden Rules in mind and refer back to them often. If you can incorporate them into your work in MUDE, you will have made good habits for yourself that we know will serve you well in the future.
We focused on illustrating good programming practices in a format and language that is approachable to engineers with a varied programming background. As such, specific fundamental programming and computer science concepts are avoided. If you would like to learn more about theses concepts, specifically related to Python, the textbook by Guttag (2021) is an excellent reference.
<divclass="alert alert-block alert-success">
<b> Note </b>
<b> Note 1 </b>
This notebook is meant to be used interactively. Use the "Live Code" button under the Rocket Ship icon in the top right to activate the page and use Python interactively!
</div>
<divclass="alert alert-block alert-success">
<b> Note 2 </b>
Whether you are a student, teacher or practitioner, we encourage you to [refer back to this document](https://mude.citg.tudelft.nl/book/programming/golden_rules.html) often and feel free to download it as a `*.ipynb` file to share. We expect to periodically update this document and perhaps share other topics in the 'Golden Rules' series.
We also greatly appreciate feedback, and are always looking for more examples of good (and bad) practices! (send to R.C.Lanzafame@tudelft.nl)
Contributors: Robert Lanzafame, Kiril Vasilev and a list of reviewers, too long to name.
</div>
%% Cell type:markdown id:e283df9f tags:
**Contents:**
-[Documentation and Communication](#Documentation-and-Communication)
-[The Golden Rules](#The-Golden-Rules)
-[References and resources](#References-and-resources)
%% Cell type:markdown id:2245c370 tags:
## Documentation and Communication
The words in the title of this lesson were chosen very carefully. *Documentation* refers to all the work related to a problem you are working on. In MUDE, documentation is not limited to describing the purpose and function of your code only. Clearly documented code is important, but in CEG it is also critical to describe all the steps in your analysis, for example: data and data sources, assumptions, results, discussion and recommendations. Jupyter notebooks provide the ideal platform for combining documentation and analysis in one file, which is why we rely on them heavily in MUDE and the focus of this lesson. However, remember there are many other options available to you for proper documentation of your work, and the topics we cover here always apply.
*Communication* refers to how you use your code, the analysis you run and the format by which you share it. Rarely are you running a piece of code purely for yourself, but often to share with others---perhaps for a homework assignment, to include in a thesis, a scientific publication, a design at a consultancy, et cetera. Why go through all the trouble of writing and using code if no one can understand what you did with it? It may be clear to you right now, but what if someone wants to use it in the future, or ask about your results, when you are not there? Will the audience understand your work if you have unreadable or overly complex tables and figures in a MSc thesis or conference presentation? Good communication is therefore critical, and there are many aspects, for example: visual formatting (visual appearance of code, text output, figures, tables); transparency and understadability (what did you do? is it repeatable? will someone understand it in the future, perhaps out of context?); and, for code explicitly: readability. This lesson provides a number of useful guidelines that will help your communication improve.
In summary, the title of this document is a bit simplistic. In reality, it should be: *the Golden Rules: a non-exhaustive list of highly recommended habits to build into your life to make sure you can easily and consistently document your work in a way that ensures effective communication with others, as well as your future self.* But that doesn’t roll off the tongue like our current title does. And it doesn’t fit in 79 characters either 😉.
1.[Write simple functions, then use them](#Rule-4:-Write-simple-functions,-then-use-them)
1.[Document your code](#Rule-5:-Document-your-code)
1.[Test your code](#Rule-6:-Test-your-code)
1.[Learn to collaborate](#Rule-7:-Learn-to-collaborate)
The sections below will provide explanations and examples of each Golden Rule, but first we need to introduce something that may seem like it belongs in a Computer Science course. However, we will see that it contains a number of useful guidelines and insight into how one can write readable Python code: the PEP-8 Style Guide.
%% Cell type:markdown id:a98880d3 tags:
## Style Guide for Python (PEP 8)
PEP stands for Python Enhancement Proposals, which is how the Python community describes new features and guidelines related to the development and (reccommended) use of the programming language. Although there are many [PEPs](https://peps.python.org/), the MUDE Golden Rules are in part inspired by one in particular: [PEP 8 - Style Guide for Python Code](https://peps.python.org/pep-0008/). PEP 8 is important because it directly addresses the readability of Python code and is thus directly aligned with the objectives of our Golden Rules. Unfortunately, PEP 8 can also seem boring, tedious and unimportant to engineers who are learning to use Python. The Golden Rules are created in part to help with this, so for now, we ask that you read carefully the [first](https://peps.python.org/pep-0008/#introduction) and [second](https://peps.python.org/pep-0008/#a-foolish-consistency-is-the-hobgoblin-of-little-minds) sections of PEP 8 to help understand the general motivation, then scan through PEP 8 to get an idea of the structure. You may want to use the website [pep8.org](https://pep8.org/), which uses text formatting and is (visually) much easier to read. Don't just open the website; you should devote at least 15 minutes reading the text and example code and consider how this might influence the way you write code. You don't need to read every word, but rather focus on the background, justification and examples for the sections that are most relevant to us:
- Code lay-out: indentation, line length, line breaks, blank lines
- Whitespace
- Comments
- Naming conventions
After around 15 minutes of reading, you should have a good idea of the general philosophy and specific ways to change the way you write Python code. Many of these guidelines are incorporated into the Golden Rules, but sometimes PEP 8 will provide more detail or background, and most importantly: example code. Therefore, you should bookmark the website and refer back to it often.
You may have noticed that checking some of the PEP 8 guidelines could be quite tedious, like counting 4 spaces on indentation or checking to make sure there are no spaces at the end of a line. This is just the type of thing that computers are good at! Fortunately there are a number of tools available to autocheck (and even autocorrect) Python code based on some (but not all!) of the reccommendations in PEP 8. The elements of PEP 8 that are most relevant to us are summarized here:
- Indentation
- Whitespace and blank lines
- Line length and line break location
- Import statements
Compliance with PEP 8 is carried out by the package [`pycodestyle`](https://pycodestyle.pycqa.org/), and you can see a detailed list of what is being checked in your code by looking at the the [list of error codes](https://pycodestyle.pycqa.org/en/latest/intro.html#error-codes). There are a few other PEP 8 guidelines that are not included in the list above or in our Golden Rules (specifically, issues in the statement and runtime groups in `pycodestyle`). If these come up as warnings or errors when reviewing your code with an autochecker you can read more about what the problem is in the PEP 8 documentation.
The next section covers PEP 8 autocheckers, but you should **always remember: only a subset the PEP 8 guidelines can be evaluated by automatic PEP 8 checkers and fixers.** For example, a computer cannot tell you whether or not your variable name is descriptive enough, or consider what variable name length is appropriate for the specific piece of code you are writing---this is something that you must determine on your own or with your team that may be hard at first, but becomes easier with a bit of practice. To convey this perspective, we adapt the quote by Martin Fowler given above:
<divstyle="text-align: right"><em>Any fool can use </em><code>autopep8</code><em> to comply with PEP 8 guidelines. Good engineers use PEP 8 carefully to write code that humans can understand.</em></div>
<divstyle="text-align: right"><em> ― MUDE Golden Rules, adapted from Martin Fowler </em></div>
%% Cell type:markdown id:a85327b9 tags:
### Checking PEP 8 automatically with `autopep8`
Although PEP 8 may look quite complicated and tedious at first glance, automatic PEP 8 formatters exist. The one we recommend you to use is `autopep8`, which can be applied on both `.py` files and `.ipynb` jupyter notebooks. A full explanation about the capabilities of this tool can be found at the [Python Package Index page](https://pypi.org/project/autopep8/).
*Bonus tip: the Python Package Index, PyPI, is the official website for Python software, where most publicly available packages can be found, and is the default source when you install packages using `pip`.*
#### Installation (Optional, but reccommended)
In order to install `autopep8`, you can simply run the following `pip` command in your terminal:
```bash
pip install autopep8
```
#### Usage
You can run the following command to auto-format python files and jupyter notebooks in-place. After the command execution has finished, your files will have been autoformatted. Make sure you replace `<filename>` with the name and extension of the file you wish to auto-format.
```bash
autopep8 --in-place <filename>
```
#### Additional Resources
`autopep8` can be added as an extension to JupyterHub, which allows you to interact with the tool through a Jupyter Notebook rather than the terminal. This can be achieved with the help of a `Jupyter Nbextensions Configurator`, which you may need to install first, before setting up `autopep8` as an extension.
Many of the IDEs such as Spyder and PyCharm contain add-ons that can be installed to automate the PEP 8 checks. Rather than providing a long list of installation instructions here, we'd encourage you to already get started with Rule X: using Google and Stack Overflow to help you identify and install a PEP 8 tool that will work for you. If you are using the JupyterHub, you can always copy and paste text into [PEP8 Online](http://pep8online.com/), as done in the first example above.
%% Cell type:markdown id:909271f9 tags:
## Rule 1: Use descriptive names
*My colleague/student constantly shares code with me but the variables are acronyms and are overwritten, which makes it difficult to read and use.*
*X1, X2, X3... oh, again X1 (overwrite). Was the previous X1 important?*
Often when you work, you will be sharing your code with other people and you need make sure that they understand what each variable is doing and how it relates to the other variables. However, this may difficult or even impossible when the variable names do not represent the purpose they have.
For example, variable names such as `a`, `a1`, `x`, `plot`, `plot1` may not be descriptive enough to use in your code. Additionally, `kruidnoten` may not be a good variable name for a weather time series plot.
Coming up with descriptive names requires practice, but when in doubt don't be afraid to use longer names to be specific. It's easy to change names in a script later with find and replace. The only downside if your names are too long is that you have to add a few more line breaks (we give you a few tips for this in ***Golden Role***), however, the downside of names that are too short is that you or a colleague has to spend hours in the future interpreting, or even rewriting your code.
However, there are some names to avoid. Namely, never use the characters `l` (lowercase letter el), `O` (uppercase letter oh), or `I` (uppercase letter eye) as single character variable names. In some fonts, these characters are indistinguishable from the numerals one and zero. When tempted to use `l`, use `L` instead. Better yet: consider a variable name that is longer than one character.
Function names should be lowercase, with words separated by underscores as necessary to improve readability:
Variable names follow the same convention as function names. We will cover some of the other naming guidelines in later tutorials. ***For now, remember: functions and variables should be written in all lower case and underscores.*** That makes it easy to remember! For everything else, you can refer to PEP 8.
%% Cell type:markdown id:a3fbc8c5 tags:
## Rule 2: Make readable code
*I hate it when a piece of code is passed to me that I cannot understand on itself.*
This rule pretty much speaks for itself, and is also the Golden Rule most closely linked to PEP 8. So rather than rewrite it, we reccommend that at the start you focus on the four aspects of PEP 8 listed here. And don't forget to read the document every once in a while to refresh your memory and see examples.
- blank lines are great for making space, but don't overuse them
- use indentation to make your line breaks readable
- space around operators, especially =, +, -, and after function arguments
- incorporate a maximum line length
The 79 character maximum line length reccommendation in PEP 8 is often a contentious one. It's important to limit line length because not all documentation software, word processers, text viewers, etc, know how to present long lines of code. Line breaks may introduced in a way that makes the code completely unreadable, or worse, large portions of your code may not be visible when printed. However, you will find that in practice it is very difficult to limit your lines to 79 characters, especially if you are using descriptive variable and function names (Golden Rule 1). On the other hand, once you learn a few tricks for making easy line breaks (below), it becomes much easier. So, our advice is to *definitely* incorporate a maximum line length in your code, but start with 79 and feel free to increase it doesn't work for a certain project. It's generally not a problem to increase the maximum length to 100 or even 120 characters, and autoformatters can be set up to help enforce this. Whatever you do, just make sure that your lines don't get cut off or broken in a way that makes your code unreadable. To help, we provide a few tips for adding line breaks to your code. Can you find the PEP 8 violations in this example? Try copying this code into [pep8online.com](http://pep8online.com/) to test yourself.
%% Cell type:code id:63b5a341 tags:
``` python
# You can always break items inside brackets wherever you like
my_sum=sum([1,
2])
bad_bracket_alignment=sum([1,
2
])
# When you split function arguments use indentation to make sure
# the entire function can be easily read with breaks
OK=sum([1,2,3,4,5,6,7,8,
9,10,11,12])
not_good=sum([1,2,3,
4,5,6,
7,8,9,10,11,12])
much_better=sum([1,2,3,4,
5,6,7,8,
9,10,11,12])
# Line breaks with strings
this_is_one_string_in_two_parts=("This string has to be split in two. "
"Notice how this line is aligned above.\n")
print(this_is_one_string_in_two_parts)
```
%% Cell type:markdown id:876df9a5 tags:
## Rule 3: Make readable results
*Your professors are old and their eyes are bad---why torture them with thin lines and tiny text on your figures?*
There are courses and books devoted to this Golden Rule, not to mention professional editors and typesetters. While you should aways make sure your results are readable, there are three main categories where it is easy to make significant improvements to readability and communication: figures, tables and numbers.
### Figures
You've gone through all the work to write code, run analyses, collect results and present them in figures. Why not spend a little extra effort to make the figure easy for your reader or audience to interpret? You should always make sure a figure contains enough information for a viewer to understand the main variables even if taken out of context, which can be done easily by including axis labels and a title, both with units, as well as a legend. Use of high contrast colors, symbols and line types is important if a lot of curves or data types are included. Finally, depending on the importance and use consider: setting good axis limits and increments (e.g., tics every 5 instead of 7), equal scale axes, grid lines, etc.
Our advice is to get in the habit of always adding a few simple commands to format to make it easy to repeat when it matters. Rather than take up space here with examples, keep an eye out for nicely formatted figures in MUDE notebooks.
### Tables
Similar to figures, make sure key information about the contents such as variable name, type and units are included. Limiting the number of significant figures to 3, adding more only when needed, can significantly improve the readability of a table. There are a number of tools available for creating tables, so we encourage you to use Google to find a few that work for your working method.
### Significant digits
Did you know that computers can store decimals up to 16 digits? If you let it, Python will try to return as many of these digits as possible. When you present results of your calculation with 6 or 8 decimal values, you give a false (and at times silly) impression of precision. For example, is that wind speed *really* 14.4613587 m/s? Especially when the accuracy of the sensor is +/-10% and the wind is gusting significantly? For most engineering purposes, 3 significant digits is plenty and can be considered a default. You can always add more if you have a good reason to do so.
Fortunately Python has a great tool to help you use an appropriate number of significant digits: `f-strings`. A few quick examples are provided below, and you can [read more about f-strings here](https://realpython.com/python-f-strings/), or any of the other good resources online.
%% Cell type:code id:725b7cc3 tags:
``` python
frommathimportpi
# Easiest f-string:
print(f'Add f before string, use curly braces to round pi = {pi:.3f}')
print(f'Different formats are possible, pi = {pi:.3e}\n')
three_things=[1.21581651,3.8,3.43454]
print('Unpack all numbers using the same format:')
print(*[f'{i:.3f}'foriinthree_things])
print('\nNow list each on a separate line:')
print(*[f'{i:.3f}'foriinthree_things],sep='\n')
```
%% Cell type:markdown id:3bfcb9b1 tags:
## Rule 4: Write simple functions, then use them
*I hate it when students/colleagues copy-paste their code with small modifications instead of using functions or classes*
Often in our code, it may be necessary to do the same thing multiple times. Without the use of functions, the code may become unreadable and there is also high risk of making errors. Take as an example the calculation of daily water use for a residential house as a function of time. You would also like to consider how this demand changes throughout the day depending on who is living in the house, specifically, the number and ages of the residents. based on the number and age of the residents as well as time of day. The following example illustrates how this is commonly evaluated when you don't think in advance about your code structure, or the use of functions.
*Note that in reality each line described below may be multiple lines in the 'real' file.*
```
1 calculate water use for 1 adult resident
2 plot result
3 copy of line 1: modified to consider teenager
4 copy of line 1: modified to consider child
5 copy of line 2: plot redrawn with 3 lines
6 copy lines 1, 4, 5 to sum water use for several users
```
Here are a few examples of how this style of code-writing can go wrong (numbers correspond to the line in the example):
- The code calculating water use as a function of time of day (1) may be wrong. Thus, the mistake will be repeated in multiple places (4, 5, 6). Extracting that code in a separate function and calling it multiple times is beneficial.
- The code becomes too long. As the calculations of water use (1) and plotting functions (2) in reality span multiple lines, the code can grow significantly. Therefore, using a separate function will reduce code duplication (3, 4, 5, 6).
- Functions (with descriptive names!) can increase code readability. Suppose you have water use calculations for different types of water users inside your code (e.g., industrial, commercial, residential). Making new functions for each will reduce the complexity of your code because the logic behind them will be placed somewhere else.
```
1 define function for water use with resident as input
2 define function to plot water use (uses function on line 1)
3 plot water use for one resident (uses line 2)
4 plot water use for multiple residents (uses line 2)
5 sum water use for several users (uses line 1)
```
It is clear that lines 1 and 2 are used repeatedly, not duplicated. If we had written out these steps entirely, rather than outlining with pseudocode, the total number of lines would be significantly less because the steps to calculate water use (1) are written once. In addition, the instructions for formatting the figure can be included in the plotting function (2).
This illustrates the concept of **modularity**: using functions to decompose the code into smaller pieces that minimize repetition and the chance of including errors. **Modules** and modular code are important general programming concepts, but also have particular significance for the Python language. This topic will be explained in a later workshop, so for now we encourage you to use functions and modularise your code. Simply taking a few moments to think about: 1) which part(s) of your analysis can be defined in a function, 2) write the functions at the top of your notebook or script (after importing your packages), then using them below, hence the name of this rule: **write simple functions, then use them.** It looks like this:
```
import Python packages
define your new functions
use your new functions
```
Would you like to learn more about this? In more general programming or computer science fields, modularity is a result of applying the concepts of *decomposition* and *abstraction.* See Guttag (2021).
*The next version of this document will also discuss hardcoding, and why it is better to pass fixed values into your function as arguments to keep the functions simple and easy to use.*
%% Cell type:markdown id:bf647dda tags:
## Rule 5: Document your code
*I had to hand over my code (semi-english, semi-dutch, unreadable and a complete mess) to real programmers about a year ago and I am still embarrassed by it.*
Do you remember what you had for dinner 2 weeks ago? If the answer is **no**, then documenting your code could be useful not only for others, but also for you.
Document what your functions and classes are doing. In addition, if you have many nested for loops or some very complex code, do not hesitate to put some in-line comments to describe what your code is doing. Overall, do not overdo it by commenting every single line, but rather try to elaborate in the way you structure your code and give names to your objects. This is why ***Golden Rule*** is closely tied to ***Rule 1: Use descriptive names***: if you do the latter, the use of the former is much less needed. Here are a few examples to illustrate unnecessary comments or poorly documented code:
```
1 x = case.one + case.too #sum
2 f = first.second.third.fourth() #gets the data
3 engineeringConcept = 2 * thisAwesomeVariable #multiplication by 2
4 global globalVariable ## define global variable globalVar
5 for i in range(200):
for j in range(300):
for k in range(i,j):
answer = (i + j)**k
6 if a and b or c and d or not b and not c:
print('here')
```
%% Cell type:markdown id:2c770286 tags:
Did you notice in example 4 that the variable name in the comment didn't match the code? Clearly the variable name changed after the comment was written. To quote PEP 8: *comments that contradict the code are worse than no comments. Always make a priority of keeping the comments up-to-date when the code changes!* Over-reliance on comments to document your code can easily result in a lot of extra work; use of descriptive object names can help minimize the number of comments necessary to provide sufficient documentation.
**Rule 5 corollary:** minimize the use of comments---instead rely on descriptive object names to narrate what your code is doing! In notebooks, you can also use markdown cells before the code cell to describe what follows.
### Comparison of bad and good documentation
The following functions are the same, the only difference is the documentation and object names, can you tell what the function does from the bad example?
%% Cell type:markdown id:c0d4b841 tags:
#### Example with bad documentation
%% Cell type:code id:e57f2a3e tags:
``` python
defHF(h,p):
return0.5*p*9.81*h**2
print('HF(10,1) = ',HP(10,1))
```
%% Cell type:markdown id:e93a3cd7 tags:
#### Example with good documentation
%% Cell type:code id:fda75b0f tags:
``` python
defforce_on_wall(wall_height,density_water):
'''Calculate hydrostatic force on a vertical wall.'''
It seems pretty obvious that the second example is more clear, and even if you understood what was happening in the first function, the second one probably would have brought you to the same conclusion much faster. And it didn't take much longer to write the second function.
The example above includes a string immediately after the function definition line (`def`), except it uses three quote symbols. This is a ***documentation string***, also known as a "***docstring***" a key tool for documenting your code. It actually has it's own PEP guideline ([PEP 257]() if you are curious), but we will cover this more on the object-oriented programming page. ***For now, our advice is to get in the habit of at least using a one-line docstring whenever you create function.***
%% Cell type:code id:69434da9 tags:
``` python
defmy_well_documented_function():
"""Illustrate a simple one-line docstring---that's it!"""
pass
```
%% Cell type:markdown id:9cc60029 tags:
You should use the imperative verb tense, a command, for example: return, integrate or compute. This helps keep the docstring compact. Compare the following one--liners with the non-imperative equivalents:
-`Compute area of circle`
-`Computes the area of a circle`
And:
-`Return int number_of_PSOR_coins`
-`Returns the number of PSOR coins as an integer`
If told us that it seems silly to write a one-line docstring for such a simple function, especially with such descriptive object names, we'd actually agree with you, especially if you were working in a small group of CEG colleagues, or by yourself. However, there is another benefit of adding a docstring: Python automatically knows to include the first line of a docsting in its built-in help functionality. Try it out here by adding a `?` after the function name (this is a handy trick that works in Jupyter notebooks).
%% Cell type:code id:65dbd634 tags:
``` python
my_well_documented_function?
```
%% Cell type:markdown id:44256b0b tags:
You can also use the `help()` function:
%% Cell type:code id:f1a76cfc tags:
``` python
help(my_well_documented_function)
```
%% Cell type:markdown id:e95e7e91 tags:
## Rule 6: Test your code
*A team member once sent me a script that predicts X for the next 5 weeks. Unfortunately, the script gave me the exact same predictions every time I used it.*
Testing that your code works properly is very important to mitigate such problems. Testing can be done in many ways, but the most simple of all is by manually running your code with different values and verifying that the final result is indeed correct.
The testing and depubbing chapter will teach you how to debug and test your code, however, for now the recommendation for you would be to test if your code is doing its job correctly by trying different variable values.
For example, suppose you have a method that calculates the volume of a pyramid given its height and base width and length. Testing the method can be done by trying different values for each of the 3 inputs and manually checking if the final volume matches your hand calculations.
%% Cell type:markdown id:7428c43d tags:
## Rule 7: Learn to collaborate
*Let me just make a new zip file of the 200MB project and send it to you via Google Drive...*
Exchanging project archives and lack of version control are key problems in project collaborations. First, the changes made are not explicitly visible, unless you go over the entire project and compare new and old versions. Second, such exchanges of files is dangerous because one may confuse which is the final version. This is especially common with file names, for example, "Document-1", "Document-2", "Document-2-Draft", "Document-2-DraftFinal", "Document-2-DraftFinal2", et cetera. Third, it hardly allows working in parallel as merging work requires manual copy-pasting of each member's progress.
In MUDE, we will cover version control systems, namely collaborating using `git` and GitLab. Although it may seem complicated at first, we are confident that once you learn about the capabilities of these systems, you will not regret it. 😉
%% Cell type:markdown id:d8658baf tags:
## References and resources
Guttag, J. V. (2021). *Introduction to Computation and Programming Using Python: With Application to Computational Modeling and Understanding Data.* MIT Press.
PEP 8 - Style Guide for Python code - https://peps.python.org/pep-0008/
Riccardo ideas. For now, when in doubt add content to the JB. Can move text to website later as needed.
<!-- Riccardo ideas. For now, when in doubt add content to the JB. Can move text to website later as needed.
1. theory + best practices with examples for efficient numerical practices
2. theory + best practices with examples of for loops (and not for loops)
3. ~~Visualization:~~
...
...
@@ -14,12 +14,18 @@ Riccardo ideas. For now, when in doubt add content to the JB. Can move text to w
3. saving results of analyses---would this be pickle? ideally we should teach them how to create a JSON and binary (pickle) format, then they choose whats best (for example, the JSON is readable and may be useful to share with a colleague who cannot run nb's in combination with a PDF printout of the nb). This is a great example where we should have content in the book that then is referred to as needed when students run into issues in submitting reports (i.e., their nb is 10 MB, now what?)
6. IDE's: a brief overview, then a recommendation and case study with Jupyter Lab and VS Code
7. package management: we need some theory on this, but it should be concise. Since Robert is already working with the TA's about environments, maybe it's best to leave this one alone till the end
8. Some handy tricks (we can make a special page on the website to quickly illustrate things described above, and provide links to the theory, explanation and case studies in the textbook)
8. Some handy tricks (we can make a special page on the website to quickly illustrate things described above, and provide links to the theory, explanation and case studies in the textbook) -->
In this textbook the programming part is a collection of pages that cover key concepts of programming and computer science without diving too far into the details. As a pre-requeisite, it is assumed you have had a BSc-level introductory course in computer programming. It is not required that it used the Python language. Over the course of the semester, content will be added to this part of the textbook and organized under the five loosely defined Chapters below:
1. This Overview page.
2. The Golden Rules: key tips and guidelines for good Documentation and Communication; we will refer to these often. THe intention is that they help you form good programming habits that you will continue to use for the rest of your life.
3. Computers & Code: this may grow to include background information about computers (e.g., how they store data) as well as information specific to the Python language (e.g., environments and package management).
4. Programs: essentials for scientific computing (e.g., modular programming; object-oriented programming, version control, Debugging and error handling
5. Communication (and documentation): visualization, version control, sharing your work
Software is also considered part of the programming learning line, but that will be covered exclusively on the module website, including instructions for installation and typical workflows.
## Why do you need Python?
Python is a computer programming language that is widely used in both academia and industries related to Civil Engineering, Environmental Engineering and Applied Earth Sciences. Being skilled in Python will help you on multiple occasions, including in your master courses.
## What can computers do for us?
As an engineer or scientist, you will deal with units of information which are called <b>data</b>. The most important tasks that a computer can do for us are:
...
...
@@ -59,8 +65,14 @@ There are five different kinds of instructions for computations you use. By orde
<b>repetition:</b>
Perform instructions repeatedly, usually with some variation.
In addition to these traditional definitions of programming, in MUDE we also extend the term to include a larger range of tasks related to computers and computer science; for example, documentation and communication of your results, or sharing your code and analysis with others. This will be described elsewhere in this part of the textbook, but for now, we will focus on the Python programming language.
## Introduction to Python
**Why do you need Python?**
Python is a computer programming language that is widely used in both academia and industries related to Civil Engineering, Environmental Engineering and Applied Earth Sciences. Being skilled in Python will help you on multiple occasions, including in your master courses. _
The features of Python are what make it so popular. From the definition available on the corresponding Wiki page: <i> "Python is an <b>interpreted</b><b>high-level</b><b>general-purpose</b><b>programming language</b>. Its design philosophy emphasizes code readability with its use of significant indentation. Its language constructs, as well as its object-oriented approach aim to help programmers write clear, logical code for small and large-scale projects."</i>. Quite a simple, yet concise description due to the meaning hidden behind each buzzword:
<ul>
...
...
@@ -75,28 +87,10 @@ Python scripts run with the help of a Python interpreter, but they can be writte
For this course we will use a slightly different approach to developing a Python script: <b>IPython</b> and <b>Jupyter Notebooks</b>. Think of these as two freely-available tools that add extra functionality to the basic Python programming language. As an example, imagine the camera built into your phone: on it's own it can take pictures, but there are many apps that add filters or sharing via social media that make the impact of your photos much more powerful. This is exactly what IPython and Jupyter Notebooks do for Python, and why they are such important tools in the toolbox of modern engineers. The next Chapter will introduce you to your Python Toolbox for this course!
Loosely broken down into 4 Chapters, with some ideas for possible contents (will fine tune location as we create it!):
1. Golden Rules (part of Communication, but introduced at beginning to set the stage)
2. Computers: essentials concepts for Scientific Computation and Numerical Analysis
1. Machine code, compilers, low- and high-level languages; Bits and bytes, storage, memory, precision; File types (e.g., txt, csv, ipynb, py, md; text and binary);
Data types (e.g., csv, JSON, netcdf, etc); FLOPS, run time; Complexity
3. Code: Instructions. Executed.
1. Programming language (Python), Environments and package management, Fundamentals of programming, Executing code, Other languages
4. Programs: essentials for scientific computing
1. Modular programming; Object-oriented programming, Version control, Debugging and error handling
5. Communication (and documentation)
1. Golden Rules, Visualization, Version control, Sharing your work (Static (*.ipynb, *.pdf, *.html) and Dynamic/Interactive (something with a Python kernel), Open-Source Projects / Collaboration
2. some of this may be moved to the website; most will be short, except git
Software is also considered a programming category, but that will be covered exclusively on the website.
**We will use this as the baseline "theory" this year with extra insight provided for use, and other topics as-needed. Links here for easy copy/paste.**
Part of the programming material for MUDE goes well beyond the scope of a typical BSc-level programming course (a MUDE pre-requisite), and part relies on the online course "Python for Engineers." Regardless of your background in Python, or programming in general, you can always benefit from learning and reviewing a few fundamentals of computer science.
## Online Course: Python for Engineers
<!-- *We will use this as the baseline "theory" this year with extra insight provided for use, and other topics as-needed. Links here for easy copy/paste.* -->
The online course [Python for Engineers](https://tudelft-citg.github.io/learn-python/intro.html) provides a series of exercises as well, which you should use to practice your understanding of the topics. Since you should have Anaconda installed for MUDE, we recommend you download the notebook pages directly, where possible, and use your own Python kernel (e.g., a Jupyter notebook as a workbook) for the chapters that only require simple calculations.
Part of the programming material for MUDE goes well beyond the scope of a typical BSc-level programming course (a MUDE pre-requisite), and part relies on the online course "Python for Engineers." Regardless of your background in Python, or programming in general, you can always benefit from learning and reviewing a few fundamentals of computer science. The online course [Python for Engineers](https://tudelft-citg.github.io/learn-python/intro.html) provides a series of exercises as well, which you should use to practice your understanding of the topics. Since you should have Anaconda installed for MUDE, we recommend you download the notebook pages directly, where possible, and use your own Python kernel (e.g., a Jupyter notebook as a workbook) for the chapters that only require simple calculations. Links to each chapter are provided here for easy reference.
Chapters from online course "Python for Engineers":
1.[Variables, operators and functions](https://tudelft-citg.github.io/learn-python/01/Theory/01.html#)
