Skip to content

Commit 4a679df

Browse files
actions-useractions-user
committed
source commit: 9600ae5 
0 parents  commit 4a679df

File tree

182 files changed

+19599
-0
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

182 files changed

+19599
-0
lines changed

‎00-setting-the-scene.md

+219
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,219 @@
1+
---
2+
title: Setting the Scene
3+
start: no
4+
colour: '#FBED65'
5+
teaching: 15
6+
exercises: 0
7+
---
8+
9+
::::::::::::::::::::::::::::::::::::::: objectives
10+
11+
- Setting the scene and expectations
12+
- Making sure everyone has all the necessary software installed
13+
14+
::::::::::::::::::::::::::::::::::::::::::::::::::
15+
16+
:::::::::::::::::::::::::::::::::::::::: questions
17+
18+
- What are we teaching in this course?
19+
- What motivated the selection of topics covered in the course?
20+
21+
::::::::::::::::::::::::::::::::::::::::::::::::::
22+
23+
## Introduction
24+
25+
So, you have gained basic software development skills either by self-learning or attending,
26+
e.g., a [novice Software Carpentry course][swc-lessons].
27+
You have been applying those skills for a while by writing code to help with your work
28+
and you feel comfortable developing code and troubleshooting problems.
29+
However, your software has now reached a point where there is too much code to be kept in one script.
30+
Perhaps it is involving more researchers (developers) and users,
31+
and more collaborative development effort is needed to add new functionality
32+
while ensuring previous development efforts remain functional and maintainable.
33+
34+
This course provides the next step in software development -
35+
it teaches some **intermediate software engineering skills and best practices**
36+
to help you restructure existing code and design more robust,
37+
reusable and maintainable code,
38+
automate the process of testing and verifying software correctness
39+
and support collaborations with others in a way that
40+
mimics a typical software development process within a team.
41+
42+
The course uses a number of different **software development tools and techniques**
43+
interchangeably as you would in a real life.
44+
We had to make some choices about topics and tools to teach here,
45+
based on established best practices,
46+
ease of tool installation for the audience,
47+
length of the course and other considerations.
48+
Tools used here are not mandated though:
49+
alternatives exist and we point some of them out along the way.
50+
Over time, you will develop a preference for certain tools and programming languages
51+
based on your personal taste
52+
or based on what is commonly used by your group, collaborators or community.
53+
However, the topics covered should give you a solid foundation for working on software development
54+
in a team and producing high quality software that is easier to develop
55+
and sustain in the future by yourself and others.
56+
Skills and tools taught here, while Python-specific,
57+
are transferable to other similar tools and programming languages.
58+
59+
The course is organised into the following sections:
60+
61+
![Course overview diagram](fig/course-overview.svg){alt="Course overview diagram. Arrows connect the following boxed text in order: 1) Setting up software environment 2) Verifying software correctness 3) Software development as a process 4) Collaborative development for reuse 5) Managing software over its lifetime."}
62+
63+
<!---
64+
Source of the above image can be rendered in the Mermaid live editor:
65+
<https://mermaid.live/edit#pako:eNpdkE1rwzAMhv-K8CmFNrCvSw6D9eO2XlbYYeSiJXJqcKwgKyml9L_PaZox5pOQn8ey3oupuCZTGOv5VB1RFN4_ygDpvGUPORxI1YUG-m5qRrZ6QiGgMDjh0FLQBZRhtXqFdfaYwyeJs-ek_OMrFqFKA8U485vsKQ2YgZoG8tyND8LkYgSETrganUnZZs85bNh7_GZBdQPd2b-2ZQGhPtJd2mUvOewxYDNu8vujSeSBBJxG8M6SupYWZmlakhZdnWK5jFRp9EgtlaZIZU0We6-lKcM1odgrH86hMoVKT0vTdzUqbR02gq0pLPqYulQ7ZdlPUd8Sn8nd7Wa2OwxfzLN3_QE4H4oo>
66+
67+
The mermaid source is (with one less dash in arrows than needed):
68+
69+
```mermaid
70+
flowchart LR
71+
A(1. Setting up software environment) -> B(2. Verifying software correctness)
72+
B -> C(3. Software development as a process)
73+
C -> D(4. Collaborative development for reuse)
74+
D -> E(5. Managing software over its lifetime)
75+
```
76+
-->
77+
78+
### [Section 1: Setting up Software Environment](10-section1-intro.md)
79+
80+
In the first section we are going to set up our working environment
81+
and familiarise ourselves with various tools and techniques for
82+
software development in a typical collaborative code development cycle:
83+
84+
- **Virtual environments** for **isolating a project** from other projects developed on the same machine
85+
- **Command line** for running code and interacting with the **command line tool Git** for
86+
- **Integrated Development Environment** for **code development, testing and debugging**,
87+
**Version control** and using code branches to develop new features in parallel,
88+
- **GitHub** (central and remote source code management platform supporting version control with Git)
89+
for **code backup, sharing and collaborative development**, and
90+
- **Python code style guidelines** to make sure our code is
91+
**documented, readable and consistently formatted**.
92+
93+
### [Section 2: Verifying Software Correctness at Scale](20-section2-intro.md)
94+
95+
Once we know our way around different code development tools, techniques and conventions,
96+
in this section we learn:
97+
98+
- how to set up a **test framework** and write tests to verify the behaviour of our code is correct, and
99+
- how to automate and scale testing with **Continuous Integration (CI)** using
100+
**GitHub Actions** (a CI service available on GitHub).
101+
102+
### [Section 3: Software Development as a Process](30-section3-intro.md)
103+
104+
In this section, we step away from writing code for a bit
105+
to look at software from a higher level as a process of development and its components:
106+
107+
- different types of **software requirements** and **designing and architecting software** to meet them,
108+
how these fit within the larger **software development process**
109+
and what we should consider when **testing** against particular types of requirements.
110+
- different **programming and software design paradigms**,
111+
each representing a slightly different way of thinking about,
112+
structuring
113+
and **implementing** the code.
114+
115+
### [Section 4: Collaborative Software Development for Reuse](40-section4-intro.md)
116+
117+
Advancing from developing code as an individual,
118+
in this section you will start working with your fellow learners
119+
on a group project (as you would do when collaborating on a software project in a team), and learn:
120+
121+
- how **code review** can help improve team software contributions,
122+
identify wider codebase issues, and increase codebase knowledge across a team.
123+
- what we can do to prepare our software for further development and reuse,
124+
by adopting best practices in
125+
**documenting**,
126+
**licencing**,
127+
**tracking issues**,
128+
**supporting** your software,
129+
and **packaging software** for release to others.
130+
131+
### [Section 5: Managing and Improving Software Over Its Lifetime](50-section5-intro.md)
132+
133+
Finally, we move beyond just software development to managing a collaborative software project and will look into:
134+
135+
- internal **planning and prioritising tasks** for future development
136+
using agile techniques and effort estimation,
137+
management of **internal and external communication**,
138+
and **software improvement** through feedback.
139+
- how to adopt a critical mindset not just towards our own software project
140+
but also to **assess other people's software to ensure it is suitable** for us to reuse,
141+
identify areas for improvement,
142+
and how to use GitHub to register good quality issues with a particular code repository.
143+
144+
## Before We Start
145+
146+
A few notes before we start.
147+
148+
::::::::::::::::::::::::::::::::::::::::: callout
149+
150+
## Prerequisite Knowledge
151+
152+
This is an intermediate-level software development course
153+
intended for people who have already been developing code in Python (or other languages)
154+
and applying it to their own problems after gaining basic software development skills.
155+
So, it is expected for you to have some prerequisite knowledge on the topics covered,
156+
as outlined at the [beginning of the lesson](../index.md#prerequisites).
157+
Check out this [quiz](../learners/quiz.md) to help you test your prior knowledge
158+
and determine if this course is for you.
159+
160+
161+
::::::::::::::::::::::::::::::::::::::::::::::::::
162+
163+
::::::::::::::::::::::::::::::::::::::::: callout
164+
165+
## Setup, Common Issues \& Fixes
166+
167+
Have you [setup and installed](../learners/setup.md) all the tools and accounts required for this course?
168+
Check the list of [common issues, fixes \& tips](../learners/common-issues.md)
169+
if you experience any problems running any of the tools you installed -
170+
your issue may be solved there.
171+
172+
173+
::::::::::::::::::::::::::::::::::::::::::::::::::
174+
175+
::::::::::::::::::::::::::::::::::::::::: callout
176+
177+
## Compulsory and Optional Exercises
178+
179+
Exercises are a crucial part of this course and the narrative.
180+
They are used to reinforce the points taught
181+
and give you an opportunity to practice things on your own.
182+
Please do not be tempted to skip exercises
183+
as that will get your local software project out of sync with the course and break the narrative.
184+
Exercises that are clearly marked as "optional" can be skipped without breaking things
185+
but we advise you to go through them too, if time allows.
186+
All exercises contain solutions but, wherever possible, try and work out a solution on your own.
187+
188+
189+
::::::::::::::::::::::::::::::::::::::::::::::::::
190+
191+
::::::::::::::::::::::::::::::::::::::::: callout
192+
193+
## Outdated Screenshots
194+
195+
Throughout this lesson we will make use and show content
196+
from Graphical User Interface (GUI) tools (PyCharm and GitHub).
197+
These are evolving tools and platforms, always adding new features and new visual elements.
198+
Screenshots in the lesson may then become out-of-sync,
199+
refer to or show content that no longer exists or is different to what you see on your machine.
200+
If during the lesson you find screenshots that no longer match what you see
201+
or have a big discrepancy with what you see,
202+
please [open an issue]({{ site.github.repository_url }}/issues/new) describing what you see
203+
and how it differs from the lesson content.
204+
Feel free to add as many screenshots as necessary to clarify the issue.
205+
206+
207+
::::::::::::::::::::::::::::::::::::::::::::::::::
208+
209+
210+
211+
:::::::::::::::::::::::::::::::::::::::: keypoints
212+
213+
- This lesson focuses on core, intermediate skills covering the whole software development life-cycle that will be of most use to anyone working collaboratively on code.
214+
- For code development in teams - you need more than just the right tools and languages. You need a strategy (best practices) for how you'll use these tools as a team.
215+
- The lesson follows on from the novice Software Carpentry lesson, but this is not a prerequisite for attending as long as you have some basic Python, command line and Git skills and you have been using them for a while to write code to help with your work.
216+
217+
::::::::::::::::::::::::::::::::::::::::::::::::::
218+
219+
[swc-lessons]: https://software-carpentry.org/lessons/

‎10-section1-intro.md

+143
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,143 @@
1+
---
2+
title: 'Section 1: Setting Up Environment For Collaborative Code Development'
3+
teaching: 10
4+
exercises: 0
5+
---
6+
7+
::::::::::::::::::::::::::::::::::::::: objectives
8+
9+
- Provide an overview of all the different tools that will be used in this course.
10+
11+
::::::::::::::::::::::::::::::::::::::::::::::::::
12+
13+
:::::::::::::::::::::::::::::::::::::::: questions
14+
15+
- What tools are needed to collaborate on code development effectively?
16+
17+
::::::::::::::::::::::::::::::::::::::::::::::::::
18+
19+
The first section of the course is dedicated to setting up your environment for collaborative software development
20+
and introducing the project that we will be working on throughout the course.
21+
In order to build working (research) software efficiently
22+
and to do it in collaboration with others rather than in isolation,
23+
you will have to get comfortable with using a number of different tools interchangeably
24+
as they will make your life a lot easier.
25+
There are many options when it comes to deciding
26+
which software development tools to use for your daily tasks -
27+
we will use a few of them in this course that we believe make a difference.
28+
There are sometimes multiple tools for the job -
29+
we select one to use but mention alternatives too.
30+
As you get more comfortable with different tools and their alternatives,
31+
you will select the one that is right for you based on your personal preferences
32+
or based on what your collaborators are using.
33+
34+
![Section 1 Overview](fig/section1-overview.svg){alt='Tools needed to collaborate on code development effectively'}
35+
36+
<!---
37+
Source of the above image can be rendered in the Mermaid live editor:
38+
<https://mermaid.live/edit#pako:eNpdkttKAzEQhl9lyIVsoS14AtkLQW3RggVRUJC9GXdn20A2s0wmLSK-u0m3K2IuQpj83z-H5MvU3JApTet4X29RFB6fKw9p3RSnc3ghVes3EHsYooFb3aMQkN9ZYd-R18oPdzNYBXaoBOgbkOghm5dp77occdbTFBKmEd1fgwAnsFosw2jzShIsZ9yrsDvYhW3OOhjeW01E2h_ix8i8iU2J9-TcbJ-OSmP2p-XT1aTys9k13BZn82xu28_U1L-GahahWj2FMIFBf1ecpxGMgoZ25LjPBR-HgQEQeuE6MwOyKC7mcMfO4QcLqt3RUfuXbllAKAY6Qsvicg5r9LjJs_6taAB5RwI2zcjZltR2NDFT05F0aJv0cF9ZVRndUkeVKdOxoRaj08pU_jtJMSq_fPralCqRpib2TXqihcWNYGfKFl1IUWqssqyHz3D4E6NyebgZ6R79O_PIff8AoRHADA>
39+
40+
The mermaid source (with one less dash in arrows than needed):
41+
42+
flowchart LR
43+
A(1. Setting up
44+
software environment
45+
46+
- Isolate and run code: command line, virtual environment & IDE
47+
- Version control and share code: Git & GitHub
48+
- Write well-written code: PEP8)
49+
50+
A -> B(2. Verifying software correctness)
51+
B -> C(3. Software development as a process)
52+
C -> D(4. Collaborative development for reuse)
53+
D -> E(5. Managing software over its lifetime)
54+
-->
55+
56+
Here is an overview of the tools we will be using.
57+
58+
::::::::::::::::::::::::::::::::::::::::: callout
59+
60+
## Setup, Common Issues \& Fixes
61+
62+
Have you [setup and installed](../learners/setup.md) all the tools and accounts required for this course?
63+
Check the list of [common issues, fixes \& tips](../learners/common-issues.md)
64+
if you experience any problems running any of the tools you installed -
65+
your issue may be solved there.
66+
67+
68+
::::::::::::::::::::::::::::::::::::::::::::::::::
69+
70+
### Command Line \& Python Virtual Development Environment
71+
72+
We will use the [command line](https://en.wikipedia.org/wiki/Shell_\(computing\))
73+
(also known as the command line shell/prompt/console)
74+
to run our Python code
75+
and interact with the version control tool Git and software sharing platform GitHub.
76+
We will also use command line tools
77+
[`venv`](https://docs.python.org/3/library/venv.html)
78+
and [`pip`](https://pip.pypa.io/en/stable/)
79+
to set up a Python virtual development environment
80+
and isolate our software project from other Python projects we may work on.
81+
82+
***Note:** some Windows users experience the issue where Python hangs from Git Bash
83+
(i.e. typing `python` causes it to just hang with no error message or output) -
84+
[see the solution to this issue](../learners/common-issues.md#python-hangs-in-git-bash).*
85+
86+
### Integrated Development Environment (IDE)
87+
88+
An IDE integrates a number of tools that we need
89+
to develop a software project that goes beyond a single script -
90+
including a smart code editor, a code compiler/interpreter, a debugger, etc.
91+
It will help you write well-formatted and readable code that conforms to code style guides
92+
(such as [PEP8](https://www.python.org/dev/peps/pep-0008/) for Python)
93+
more efficiently by giving relevant and intelligent suggestions
94+
for code completion and refactoring.
95+
IDEs often integrate command line console and version control tools -
96+
we teach them separately in this course
97+
as this knowledge can be ported to other programming languages
98+
and command line tools you may use in the future
99+
(but is applicable to the integrated versions too).
100+
101+
We will use [PyCharm](https://www.jetbrains.com/pycharm/) in this course -
102+
a free, open source IDE.
103+
104+
### Git \& GitHub
105+
106+
[Git](https://git-scm.com/) is a free and open source distributed version control system
107+
designed to save every change made to a (software) project,
108+
allowing others to collaborate and contribute.
109+
In this course, we use Git to version control our code in conjunction with [GitHub](https://github.com/)
110+
for code backup and sharing.
111+
GitHub is one of the leading integrated products and social platforms
112+
for modern software development, monitoring and management -
113+
it will help us with
114+
version control,
115+
issue management,
116+
code review,
117+
code testing/Continuous Integration,
118+
and collaborative development.
119+
An important concept in collaborative development is version control workflows
120+
(i.e. how to effectively use version control on a project with others).
121+
122+
### Python Coding Style
123+
124+
Most programming languages will have associated standards and conventions for how the source code
125+
should be formatted and styled.
126+
Although this sounds pedantic,
127+
it is important for maintaining the consistency and readability of code across a project.
128+
Therefore, one should be aware of these guidelines
129+
and adhere to whatever the project you are working on has specified.
130+
In Python, we will be looking at a convention called PEP8.
131+
132+
Let us get started with setting up our software development environment!
133+
134+
135+
136+
:::::::::::::::::::::::::::::::::::::::: keypoints
137+
138+
- In order to develop (write, test, debug, backup) code efficiently, you need to use a number of different tools.
139+
- When there is a choice of tools for a task you will have to decide which tool is right for you, which may be a matter of personal preference or what the team or community you belong to is using.
140+
141+
::::::::::::::::::::::::::::::::::::::::::::::::::
142+
143+

0 commit comments

Comments
 (0)