Skip to content

Commit 0fb6d1b

Browse files
actions-useractions-user
committed
source commit: abf9017 
0 parents  commit 0fb6d1b

209 files changed

Lines changed: 19595 additions & 0 deletions

File tree

Some content is hidden

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

‎00-setting-the-scene.md‎

Lines changed: 215 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,215 @@
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+
```mermaid
62+
flowchart LR
63+
accTitle: Overview of sections in the lesson
64+
accDescr {Course overview diagram. Arrows connect the following boxed
65+
text in order: 1) Setting up software environment 2) Verifying software
66+
correctness 3) Software development as a process 4) Collaborative
67+
development for reuse 5) Managing software over its lifetime.}
68+
A(1. Setting up software environment) --> B(2. Verifying software correctness)
69+
B --> C(3. Software development as a process)
70+
C --> D(4. Collaborative development for reuse)
71+
D --> E(5. Managing software over its lifetime)
72+
```
73+
74+
### [Section 1: Setting up Software Environment](10-section1-intro.md)
75+
76+
In the first section we are going to set up our working environment
77+
and familiarise ourselves with various tools and techniques for
78+
software development in a typical collaborative code development cycle:
79+
80+
- **Virtual environments** for **isolating a project** from other projects developed on the same machine
81+
- **Command line** for running code and interacting with the **command line tool Git** for
82+
- **Integrated Development Environment** for **code development, testing and debugging**,
83+
**Version control** and using code branches to develop new features in parallel,
84+
- **GitHub** (central and remote source code management platform supporting version control with Git)
85+
for **code backup, sharing and collaborative development**, and
86+
- **Python code style guidelines** to make sure our code is
87+
**documented, readable and consistently formatted**.
88+
89+
### [Section 2: Verifying Software Correctness at Scale](20-section2-intro.md)
90+
91+
Once we know our way around different code development tools, techniques and conventions,
92+
in this section we learn:
93+
94+
- how to set up a **test framework** and write tests to verify the behaviour of our code is correct, and
95+
- how to automate and scale testing with **Continuous Integration (CI)** using
96+
**GitHub Actions** (a CI service available on GitHub).
97+
98+
### [Section 3: Software Development as a Process](30-section3-intro.md)
99+
100+
In this section, we step away from writing code for a bit
101+
to look at software from a higher level as a process of development and its components:
102+
103+
- different types of **software requirements** and **designing and architecting software** to meet them,
104+
how these fit within the larger **software development process**
105+
and what we should consider when **testing** against particular types of requirements.
106+
- different **programming and software design paradigms**,
107+
each representing a slightly different way of thinking about,
108+
structuring
109+
and **implementing** the code.
110+
111+
### [Section 4: Collaborative Software Development for Reuse](40-section4-intro.md)
112+
113+
Advancing from developing code as an individual,
114+
in this section you will start working with your fellow learners
115+
on a group project (as you would do when collaborating on a software project in a team), and learn:
116+
117+
- how **code review** can help improve team software contributions,
118+
identify wider codebase issues, and increase codebase knowledge across a team.
119+
- what we can do to prepare our software for further development and reuse,
120+
by adopting best practices in
121+
**documenting**,
122+
**licencing**,
123+
**tracking issues**,
124+
**supporting** your software,
125+
and **packaging software** for release to others.
126+
127+
### [Section 5: Managing and Improving Software Over Its Lifetime](50-section5-intro.md)
128+
129+
Finally, we move beyond just software development to managing a collaborative software project and will look into:
130+
131+
- internal **planning and prioritising tasks** for future development
132+
using agile techniques and effort estimation,
133+
management of **internal and external communication**,
134+
and **software improvement** through feedback.
135+
- how to adopt a critical mindset not just towards our own software project
136+
but also to **assess other people's software to ensure it is suitable** for us to reuse,
137+
identify areas for improvement,
138+
and how to use GitHub to register good quality issues with a particular code repository.
139+
140+
## Before We Start
141+
142+
A few notes before we start.
143+
144+
::::::::::::::::::::::::::::::::::::::::: callout
145+
146+
## Prerequisite Knowledge
147+
148+
This is an intermediate-level software development course
149+
intended for people who have already been developing code in Python (or other languages)
150+
and applying it to their own problems after gaining basic software development skills.
151+
So, it is expected for you to have some prerequisite knowledge on the topics covered,
152+
as outlined at the [beginning of the lesson](../index.md#prerequisites).
153+
Check out this [quiz](../learners/quiz.md) to help you test your prior knowledge
154+
and determine if this course is for you.
155+
156+
157+
::::::::::::::::::::::::::::::::::::::::::::::::::
158+
159+
::::::::::::::::::::::::::::::::::::::::: callout
160+
161+
## Setup, Common Issues \& Fixes
162+
163+
Have you [setup and installed](../learners/setup.md) all the tools and accounts required for this course?
164+
Check the list of [common issues, fixes \& tips](../learners/common-issues.md)
165+
if you experience any problems running any of the tools you installed -
166+
your issue may be solved there.
167+
168+
169+
::::::::::::::::::::::::::::::::::::::::::::::::::
170+
171+
::::::::::::::::::::::::::::::::::::::::: callout
172+
173+
## Compulsory and Optional Exercises
174+
175+
Exercises are a crucial part of this course and the narrative.
176+
They are used to reinforce the points taught
177+
and give you an opportunity to practice things on your own.
178+
Please do not be tempted to skip exercises
179+
as that will get your local software project out of sync with the course and break the narrative.
180+
Exercises that are clearly marked as "optional" can be skipped without breaking things
181+
but we advise you to go through them too, if time allows.
182+
All exercises contain solutions but, wherever possible, try and work out a solution on your own.
183+
184+
185+
::::::::::::::::::::::::::::::::::::::::::::::::::
186+
187+
::::::::::::::::::::::::::::::::::::::::: callout
188+
189+
## Outdated Screenshots
190+
191+
Throughout this lesson we will make use and show content
192+
from Graphical User Interface (GUI) tools such as Integrated Development Environments (IDEs) and GitHub.
193+
These are evolving tools and platforms, always adding new features and new visual elements.
194+
Screenshots in the lesson may then become out-of-sync,
195+
refer to or show content that no longer exists or is different to what you see on your machine.
196+
If during the lesson you find screenshots that no longer match what you see
197+
or have a big discrepancy with what you see,
198+
please [open an issue]({{ site.github.repository_url }}/issues/new) describing what you see
199+
and how it differs from the lesson content.
200+
Feel free to add as many screenshots as necessary to clarify the issue.
201+
202+
203+
::::::::::::::::::::::::::::::::::::::::::::::::::
204+
205+
206+
207+
:::::::::::::::::::::::::::::::::::::::: keypoints
208+
209+
- 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.
210+
- 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.
211+
- 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.
212+
213+
::::::::::::::::::::::::::::::::::::::::::::::::::
214+
215+
[swc-lessons]: https://software-carpentry.org/lessons/

‎10-section1-intro.md‎

Lines changed: 135 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,135 @@
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+
```mermaid
35+
flowchart LR
36+
accDescr {Topics on effective collaborating on code development covered in
37+
the current section: virtual development environments, version control &
38+
sharing code, writing readable code & code standards}
39+
A("`1. Setting up software environment
40+
- Isolating & running code: command line, virtual environment & IDE
41+
- Version control and sharing code: Git & GitHub
42+
- Well-written & readable code: PEP8`")
43+
A --> B(2. Verifying software correctness)
44+
B --> C(3. Software development as a process)
45+
C --> D(4. Collaborative development for reuse)
46+
D --> E(5. Managing software over its lifetime)
47+
```
48+
49+
Here is an overview of the tools we will be using.
50+
51+
::::::::::::::::::::::::::::::::::::::::: callout
52+
53+
## Setup, Common Issues \& Fixes
54+
55+
Have you [setup and installed](../learners/setup.md) all the tools and accounts required for this course?
56+
Check the list of [common issues, fixes \& tips](../learners/common-issues.md)
57+
if you experience any problems running any of the tools you installed -
58+
your issue may be solved there.
59+
60+
61+
::::::::::::::::::::::::::::::::::::::::::::::::::
62+
63+
### Command Line \& Python Virtual Development Environment
64+
65+
We will use the [command line](https://en.wikipedia.org/wiki/Shell_\(computing\))
66+
(also known as the command line shell/prompt/console)
67+
to run our Python code
68+
and interact with the version control tool Git and software sharing platform GitHub.
69+
We will also use command line tools
70+
[`venv`](https://docs.python.org/3/library/venv.html)
71+
and [`pip`](https://pip.pypa.io/en/stable/)
72+
to set up a Python virtual development environment
73+
and isolate our software project from other Python projects we may work on.
74+
75+
***Note:** some Windows users experience the issue where Python hangs from Git Bash
76+
(i.e. typing `python` causes it to just hang with no error message or output) -
77+
[see the solution to this issue](../learners/common-issues.md#python-hangs-in-git-bash).*
78+
79+
### Integrated Development Environment (IDE)
80+
81+
An IDE integrates a number of tools that we need
82+
to develop a software project that goes beyond a single script -
83+
including a smart code editor, a code compiler/interpreter, a debugger, etc.
84+
It will help you write well-formatted and readable code that conforms to code style guides
85+
(such as [PEP8](https://www.python.org/dev/peps/pep-0008/) for Python)
86+
more efficiently by giving relevant and intelligent suggestions
87+
for code completion and refactoring.
88+
IDEs often integrate command line console and version control tools -
89+
we teach them separately in this course
90+
as this knowledge can be ported to other programming languages
91+
and command line tools you may use in the future
92+
(but is applicable to the integrated versions too).
93+
94+
You have a choice of using [PyCharm](https://www.jetbrains.com/pycharm/) or [Visual Studio Code (VS Code)](https://code.visualstudio.com/) in this course.
95+
96+
### Git \& GitHub
97+
98+
[Git](https://git-scm.com/) is a free and open source distributed version control system
99+
designed to save every change made to a (software) project,
100+
allowing others to collaborate and contribute.
101+
In this course, we use Git to version control our code in conjunction with [GitHub](https://github.com/)
102+
for code backup and sharing.
103+
GitHub is one of the leading integrated products and social platforms
104+
for modern software development, monitoring and management -
105+
it will help us with
106+
version control,
107+
issue management,
108+
code review,
109+
code testing/Continuous Integration,
110+
and collaborative development.
111+
An important concept in collaborative development is version control workflows
112+
(i.e. how to effectively use version control on a project with others).
113+
114+
### Python Coding Style
115+
116+
Most programming languages will have associated standards and conventions for how the source code
117+
should be formatted and styled.
118+
Although this sounds pedantic,
119+
it is important for maintaining the consistency and readability of code across a project.
120+
Therefore, one should be aware of these guidelines
121+
and adhere to whatever the project you are working on has specified.
122+
In Python, we will be looking at a convention called PEP8.
123+
124+
Let us get started with setting up our software development environment!
125+
126+
127+
128+
:::::::::::::::::::::::::::::::::::::::: keypoints
129+
130+
- In order to develop (write, test, debug, backup) code efficiently, you need to use a number of different tools.
131+
- 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.
132+
133+
::::::::::::::::::::::::::::::::::::::::::::::::::
134+
135+

0 commit comments

Comments
 (0)