diff --git a/.gitignore b/.gitignore index 0e74568..947dde2 100644 --- a/.gitignore +++ b/.gitignore @@ -99,4 +99,5 @@ ENV/ # mypy .mypy_cache/ -getting_started/tiles/* + +software_engineering/tiles/* diff --git a/getting_started/prototype.png b/getting_started/prototype.png deleted file mode 100644 index 0ae8d4e..0000000 Binary files a/getting_started/prototype.png and /dev/null differ diff --git a/index.rst b/index.rst index 2fe0fe5..45a4aa9 100644 --- a/index.rst +++ b/index.rst @@ -15,13 +15,22 @@ piece of software is more complex. You are facing questions like: Below you find development tools and techniques that help you to write programs that get the job done and don’t fall apart. +Developing Software +------------------- + +.. toctree:: + :maxdepth: 1 + + software_engineering/README.rst + software_engineering/prototype.rst + software_engineering/code_review.rst + Setting up a Python Project --------------------------- .. toctree:: :maxdepth: 1 - getting_started/prototype.rst getting_started/virtualenv.rst getting_started/git_repo.rst getting_started/structure.rst diff --git a/software_engineering/README.rst b/software_engineering/README.rst new file mode 100644 index 0000000..ffdcf25 --- /dev/null +++ b/software_engineering/README.rst @@ -0,0 +1,99 @@ + +The Dungeon Explorer Game +========================= + +.. image:: title.png + +*image generated with dreamstudio* + +In the following chapters, we will write a small game called **Dungeon Explorer**. +Writing a game is a great way to both become better at programming and to exemplify a systematic approach to programming. + +What Software Development is about +---------------------------------- + +.. image:: software_engineering.png + +Software development is more than writing code. +While most courses and online resources focus very much on the process of writing code, +it is easy to forget that several things that are necessary before the code can be written: + +* an **idea** that provides a reason for the program to exist (*"why"*) +* **requirements** that describe what the program should do (*"what"*) +* a **design** that describes core mechanics of the program (*"how"*) +* the actual **implementation** + +When moving from the idea towards code, one gradually translates the informal, prose description of the problem into a *formal language*. Much of it requires gaining a deeper understanding of a task that is unknown at first. This is what much of a software developers work is really about. + +In a simple program, like many learning examples and coding challenges, the first three steps are nonexistent or at least very easy. +In any real-world software project, the first three steps are often more difficult than the implementation. +When writing requirements or designing a program, the software developer does not only have to find a path that brings the original idea to life, but also anticipate what forces the software will have to adapt to in the future. + +Let's look at an example of how the first three steps would look for a **Dungeon Explorer** game: + +The Idea +-------- + +*"In the Dungeon Explorer game, an adventurer roams a dungeon, solves puzzles, avoids traps and finds treasures."* + +The Requirements +---------------- + +Here is a short example of how the idea could be fleshed out more: + +1. User Interface +~~~~~~~~~~~~~~~~~ + +=== ============================================================== +# description +=== ============================================================== +1.1 The dungeon is seen from the top as a 2D grid +1.2 The dungeon is drawn from square graphic tiles +1.3 The adventurer is controlled by the player by pressing keys +=== ============================================================== + +2. Dungeon Elements +~~~~~~~~~~~~~~~~~~~ + +=== ============================================================== +# description +=== ============================================================== +2.1 There are walls that are impassable +2.2 There is an exit square that leads to the next level +2.3 There are keys that are needed to open doors +=== ============================================================== + +3. Traps +~~~~~~~~ + +=== ============================================================== +# description +=== ============================================================== +3.1 There are pits. If the player falls into one, they die +3.2 There is green slime where the player loses health +3.3 There are fireballs that travel in straight lines +=== ============================================================== + +The Design +---------- + +Two key elements of the game deserve to be described better. +First, the grid that is used for the dungeon is based on *integer x/y coordinates*: + +.. image:: grid_model.png + +Second, the following **flowchart** describes how the program actually works: + +.. image:: flowchart.png + +.. note:: + + At this point, we have not decided what libraries or even what programming language to use. This is good, because the design makes the task more specific without constraining the developer. + +These are just two examples of design techniques. +For a first implementation, see the next chapter. + +Reflection Questions +-------------------- + +- which of the in the software development diagram could be automated with the help of a Large Language Model (LLM)? \ No newline at end of file diff --git a/software_engineering/code_review.rst b/software_engineering/code_review.rst new file mode 100644 index 0000000..aa2b549 --- /dev/null +++ b/software_engineering/code_review.rst @@ -0,0 +1,62 @@ +Code Reviews +============ + +A **Code review** means that another person reads your code. This could +be: + +- a senior engineer +- a programmer with similar experience +- a junior developer + +All three provide complementary feedback that is useful in many ways. +Besides discovering bugs, they also expose general design weaknesses +(that might become bugs in the future) or simply learn you +alternative/better ways to solve the problem. + +Because of that, many engineers see code reviews as the +**number one technique to build high-quality software.** + + +Exercise 1: Code Review +----------------------- + +Inspect the Python code in :download:`prototype_opencv.py`. +Answer the following questions: + +* What libraries does the program use? +* What variables does the program define? +* What do the functions do? +* Which parts of the code correspond to the flowchart? +* How are the grid coordinates represented? +* What would you like to know more about? + +Exercise 2: Modify +------------------ + +Extend the code such that: + +* the player can be moved up and down. +* the player stops at the border of the screen +* the player respawns at the left if they leave the grid on the right side +* there is a "teleport" key that jumps to a random grid point + + +.. topic:: What to look for in a code review? + + Here are a few things to pay attention to in a code review. + The list is by far not exhaustive: + + - Does the module header explain understandably what the code does? + - Are constants listed right after the import statements? + - Is the code sufficiently documented? + - Are the functions understandable? + - Are the variable names descriptive + - Is the code formatted in a consistent way? + - Are there code duplications? + - Is there dead code that does nothing? + - Are there code sections that are unnecessarily long? + - Are there while loops that could run forever? + - Are there deeply nested code sections? + - Do all functions have exactly one way to return data (either by + return value OR by modifying an object, not both). + \ No newline at end of file diff --git a/software_engineering/flowchart.png b/software_engineering/flowchart.png new file mode 100644 index 0000000..f596288 Binary files /dev/null and b/software_engineering/flowchart.png differ diff --git a/software_engineering/flowchart.svg b/software_engineering/flowchart.svg new file mode 100644 index 0000000..c1dcb21 --- /dev/null +++ b/software_engineering/flowchart.svg @@ -0,0 +1,452 @@ + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + START + + END yes + + modify player position + + + draw player on screen + + + set player position to (4,4) + + + exit key pressed? + + + + + + + + no + diff --git a/software_engineering/grid_model.png b/software_engineering/grid_model.png new file mode 100644 index 0000000..b0643b9 Binary files /dev/null and b/software_engineering/grid_model.png differ diff --git a/software_engineering/grid_model.svg b/software_engineering/grid_model.svg new file mode 100644 index 0000000..b04a327 --- /dev/null +++ b/software_engineering/grid_model.svg @@ -0,0 +1,312 @@ + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 0 1 2 3 0 1 2 3 x y + diff --git a/software_engineering/prototype.png b/software_engineering/prototype.png new file mode 100644 index 0000000..6552cd6 Binary files /dev/null and b/software_engineering/prototype.png differ diff --git a/getting_started/prototype.rst b/software_engineering/prototype.rst similarity index 85% rename from getting_started/prototype.rst rename to software_engineering/prototype.rst index fabf7b2..4d38ac8 100644 --- a/getting_started/prototype.rst +++ b/software_engineering/prototype.rst @@ -18,10 +18,6 @@ A prototype can answer questions like: A Prototype for Dungeon Explorer -------------------------------- -.. image:: title.png - -*image generated with dreamstudio* - Let's look at a prototype for a Dungeon Explorer game. In the program you move a graphical icon using the keyboard. The goal of this prototype is to prove that you can process keyboard input @@ -64,20 +60,8 @@ Change to the directory with the ``.py`` file and execute the code with: You should see a screen where you can move a character with the keys **A and D**: +.. image:: prototype.png -Exercise 4: Code Review ------------------------ - -Inspect the Python file. Take notes to answer the following questions: - -* What do you like about the code? -* What do you not like about the code? -* What would you like to know more about? - -Exercise 5: Modify ------------------- - -Add the two missing directions. Reflection Questions -------------------- diff --git a/getting_started/prototype_curses.py b/software_engineering/prototype_curses.py similarity index 100% rename from getting_started/prototype_curses.py rename to software_engineering/prototype_curses.py diff --git a/getting_started/prototype_opencv.py b/software_engineering/prototype_opencv.py similarity index 100% rename from getting_started/prototype_opencv.py rename to software_engineering/prototype_opencv.py diff --git a/software_engineering/software_engineering.png b/software_engineering/software_engineering.png new file mode 100644 index 0000000..54d6796 Binary files /dev/null and b/software_engineering/software_engineering.png differ diff --git a/software_engineering/software_engineering.svg b/software_engineering/software_engineering.svg new file mode 100644 index 0000000..6bba077 --- /dev/null +++ b/software_engineering/software_engineering.svg @@ -0,0 +1,242 @@ + + + + + + + + + + image/svg+xml + + + + + + + + + Idea Requirements Design Implementation + + + + + + + + + + + + + + formal language prose + diff --git a/getting_started/tiles.zip b/software_engineering/tiles.zip similarity index 100% rename from getting_started/tiles.zip rename to software_engineering/tiles.zip diff --git a/getting_started/title.png b/software_engineering/title.png similarity index 100% rename from getting_started/title.png rename to software_engineering/title.png