Merge branch 'master' into constructors

Author: diehlpk

sources/knowledge_areas.dat

@@ -55,6 +55,11 @@ EH Error Handling
 	? ? ? ? errno
 	? ? ? ? Error Codes
 	eh y y y Exception Handling
+PD Program Design
+	cont y y y Containers
+DE Debugging Errors
+	compiletimeerr y y y Compile-Time Errors
+	runtimeerr y y y Run-time Errors
 SL Standard Library
 	? ? ? ? Input/Output (I/O)
 	? ? ? ? Containers, Iterators, and Algorithms

sources/modules/debugging-errors/build-errors.md

@@ -0,0 +1,6 @@
+## Debugging Errors: Build errors
+
+_Skeleton descriptions are typeset in italic text,_
+_so please don't remove these descriptions when editing the topic._
+
+This topic is currently under construction and will soon be filled with information :)

sources/modules/debugging-errors/compiletime-errors.md

@@ -0,0 +1,114 @@
+## Debugging Errors: Compile-time errors {#compiletimeerr}
+
+_Skeleton descriptions are typeset in italic text,_
+_so please don't remove these descriptions when editing the topic._
+
+### Overview
+
+_Provides a short natural language abstract of the module’s contents._
+_Specifies the different levels of teaching._
+
+------------------------------------------------------------------------
+Level             Objective
+----------------- ------------------------------------------------------
+Foundational      Understanding elementary error messages
+
+Main              Dealing with most error messages
+
+Advanced          ---
+
+------------------------------------------------------------------------
+
+### Motivation
+
+_Why is this important?_
+_Why do we want to learn/teach this topic?_
+
+Compiler error messages can be hard to read and even compiler specific.
+However, they contain valuable information for determining the cause of the compile-time errors.
+Oftentimes the error messages are very verbose to give you the most precise information about the error context, so learning how to extract the valuable information from the error message is an important skill that one should acquire.
+
+### Topic introduction
+
+_Very brief introduction to the topic._
+
+C++ compilers try to statically determine errors at compile time to shift detection of problems that would occur later on (e.g., at link time or run time) to earlier point in time, where they can be addressed in an earlier stage of the development process.
+The error message that the compiler generates directly relates to the C++ language definition and precisely lays out why the code is not valid and where it does not comply with the language rules.
+
+### Foundational: Understanding elementary error messages {#compiletimeerr-found}
+
+#### Background/Required Knowledge
+
+A student:
+
+* definitions [[C++ Object Model: Definitions - Foundational]][1]
+
+#### Student outcomes
+
+_A list of things "a student should be able to" after the curriculum._
+_The next word should be an action word and testable in an exam._
+_Max 5 items._
+
+A student should be able to:
+
+1. distill the core of an elementary error message.
+2. act on elementary error messages.
+3. differentiate between different error kinds (e.g., type errors, syntax errors, ...).
+4. give examples for different kinds of errors.
+
+
+#### Caveats
+
+_This section mentions subtle points to understand, like anything resulting in
+implementation-defined, unspecified, or undefined behavior._
+
+* names mentioned in error message are presented in full detail and may not look exactly like specified by the programmer (e.g., `std::string` -> `std::basic_string<char>`)
+
+#### Points to cover
+
+_This section lists important details for each point._
+
+* methodology of reading error messages
+    * start with the first error
+    * read top down
+    * parse error message / pattern matching to error kinds
+* linker errors [[Debugging Errors: Build errors - Foundational]][2]
+
+
+### Main: Dealing with most error messages {#compiletimeerr-main}
+
+#### Background/Required Knowledge
+
+* compile-time programming [Soft dependency]
+
+#### Student outcomes
+
+A student should be able to:
+
+1. locate the principle template involved in a template error message.
+2. determine why a specific overload is chosen, from the compiler’s error message.
+3. apply common debugging techniques in a constexpr context.
+
+#### Caveats
+
+* argument dependent lookup
+* there is currently no good debugger support for constexpr context
+
+#### Points to cover
+
+* templates related error messages
+* overload resolution related errors
+* reasoning about errors during constexpr execution (consteval)
+    * reverting to non-constexpr run-time debugging
+    * employing static_assert
+
+### Advanced
+
+_These are important topics that are not expected to be covered but provide
+guidance where one can continue to investigate this topic in more depth._
+
+* Full error analysis, there are error messages that are out of the scope for students.
+    * Complicated SFINAE constructs
+
+[1]: ../object-model/definitions.md
+[2]: ../debugging-errors/build-errors.md

sources/modules/debugging-errors/runtime-errors.md

@@ -0,0 +1,113 @@
+## Debugging errors: Run-time errors {#runtimeerr}
+
+_Skeleton descriptions are typeset in italic text,_
+_so please don't remove these descriptions when editing the topic._
+
+### Overview
+
+_Provides a short natural language abstract of the module’s contents._
+_Specifies the different levels of teaching._
+
+------------------------------------------------------------------------
+Level             Objective
+----------------- ------------------------------------------------------
+Foundational      Identifying the run-time error cause
+
+Main              Introspection methodologies to trackdown run-time errors
+
+Advanced          ---
+
+------------------------------------------------------------------------
+
+### Motivation
+
+_Why is this important?_
+_Why do we want to learn/teach this topic?_
+
+Code correctness is important, as erroneous programs can lead to real-world catastrophes, take for example, medical equipment failures that lead to people being exposed to too much radiation.
+Techniques, such as, testing or fuzzing, help developers to identify erroneous states of the program.
+However, when these techniques discover a run-time error, it’s up to the programmer to reason about and find the root cause of such run-time errors, so they need a well established process to debug run-time errors.
+
+### Topic introduction
+
+_Very brief introduction to the topic._
+
+There exists a wide variety of methodologies, techniques, and tools to debug run-time errors.
+In this topic, we give an overview of these and highlight how they can be applied to track down run-time errors in C++ programs.
+
+### Foundational: Identifying the run-time error cause {#runtimeerr-found}
+
+#### Background/Required Knowledge
+
+A student:
+
+* should be able to produce a basic running program.
+
+#### Student outcomes
+
+_A list of things "a student should be able to" after the curriculum._
+_The next word should be an action word and testable in an exam._
+_Max 5 items._
+
+A student should be able to:
+
+1. verify the output of the program and identify incorrect outcomes.
+2. phrase hypothesis what could cause the run-time error.
+3. observe and extract program state at specific points of the program, to verify hypotheses.
+4. make their program as observable as possible.
+
+#### Caveats
+
+_This section mentions subtle points to understand, like anything resulting in
+implementation-defined, unspecified, or undefined behavior._
+
+* run-time debugging can be domain specific
+* not everything about the program state can be easily observed, students should be aware of that and learn basic techniques to make programs more observable
+* students should be aware that the compilation mode (optimized vs debug) affects the debugging experience and also the program state itself
+
+
+#### Points to cover
+
+_This section lists important details for each point._
+
+* the basics of using a debugger
+* compiling with debug information
+* observability techniques, such as, logging output or even `printf` statements
+
+### Main: Introspection methodologies to trackdown run-time errors {#runtimeerr-main}
+
+#### Background/Required Knowledge
+
+* All of the above.
+
+#### Student outcomes
+
+A student should be able to:
+
+1. use a debugger to inspect and manipulate program state
+2. extract crash information using proper libraries
+3. can create a minimal reproducible example
+
+#### Caveats
+
+* Different forms of multiprocessing programs can have varying impact on debuggability, such as:
+    * parallel stl algorithms
+    * multi threading
+    * coroutines
+    * vector parallelism
+
+
+#### Points to cover
+
+* How to use debuggers and the multitude of features they offer to manipulate and observe program state (e.g., break points, trap points, stack traces, manipulating program state).
+* Use (non) standard library support for crash information extraction, e.g., logging libraries, libraries to capture crash reports, and sanitizer libraries (asan/ubsan/tsan).
+* Creating minimal reproducible example and regressions tests from the extracted crash information.
+
+
+### Advanced {#runtimeerr-advanced}
+
+_These are important topics that are not expected to be covered but provide
+guidance where one can continue to investigate this topic in more depth._
+
+* ABI incompatibilities can have impact debugging experience where even observability tools, such as, debuggers, cannot correctly show the state of the program.
+* Debugging in embedded environments.

sources/modules/program-design/algorithms.md

@@ -0,0 +1,6 @@
+## Program Design: Algorithms
+
+_Skeleton descriptions are typeset in italic text,_
+_so please don't remove these descriptions when editing the topic._
+
+This topic is currently under construction and will soon be filled with information :)

sources/modules/program-design/containers.md

@@ -0,0 +1,125 @@
+## Program Design: Containers {#cont}
+
+_Skeleton descriptions are typeset in italic text,_
+_so please don't remove these descriptions when editing the topic._
+
+### Overview
+
+_Provides a short natural language abstract of the module’s contents._
+_Specifies the different levels of teaching._
+
+------------------------------------------------------------------------
+Level             Objective
+----------------- ------------------------------------------------------
+Foundational      Using standard containers
+
+Main              Extending standard containers and day-to-day usages
+
+Advanced          ---
+
+------------------------------------------------------------------------
+
+### Motivation
+
+_Why is this important?_
+_Why do we want to learn/teach this topic?_
+
+Storing data is an essential part of computations.
+We use abstractions to make it easier to reason about and work with the data.
+This leads to grouping related data variables together in data structures to give the grouping a name and to be able to make multiple instances of that data structure.
+Data structures are therefore foundational building blocks for program design and are present in almost every program. 
+
+Data structures come in many different forms, but there are special data structures that group objects of related types together.
+In C++ these collections of data are called containers.
+The C++ standard library provides a wide range of such common containers.
+To make algorithms more universally applicable to containers, the standard library defines a common interface.
+This way, containers build a bridge between algorithms and how data is organized.
+
+
+### Topic introduction
+
+_Very brief introduction to the topic._
+
+### Foundational: Using standard containers {#cont-found}
+
+#### Background/Required Knowledge
+
+A student:
+
+* "for loops"
+* "defining variables"
+* "main function"
+
+#### Student outcomes
+
+_A list of things "a student should be able to" after the curriculum._
+_The next word should be an action word and testable in an exam._
+_Max 5 items._
+
+A student should be able to:
+
+1. setup and add objects to a container
+2. work with objects that are stored in a container
+
+#### Caveats
+
+_This section mentions subtle points to understand, like anything resulting in
+implementation-defined, unspecified, or undefined behavior._
+
+* On a foundational level, avoid using iterators when teaching containers to prevent problems, such as iterator invalidation or dangling iterators.
+* Avoid going deep into the template notation
+* Teach people to not use `vector<bool>`
+
+#### Points to cover
+
+_This section lists important details for each point._
+
+* Creating containers, adding objects, iterating over them using range based or index based for loops.
+* `vector`, `string`, `unordered_map`, `unordered_set`
+* Notation for having container of different value types with angle brackets
+
+
+### Main: Extending standard containers and day-to-day usages {#cont-main}
+
+#### Background/Required Knowledge
+
+* Basic understanding of standard algorithms [[Program Design: Algorithms - Foundational]][1]
+* Basic understanding of classes and class templates [[User-defined Types: Class Templates - Foundational]][2]
+
+#### Student outcomes
+
+A student should be able to:
+
+1. make effective use of the standard containers.
+2. make use of iterators to iterate over a sequence and call algorithms.
+3. make a proper choice what container to use based on its characteristics.
+4. write a container class template for a specific need (based on a standard container).
+5. make use of common container idioms.
+
+#### Caveats
+
+* Iterator invalidation
+* When extending standard containers, prefer delegation over inheritance
+
+#### Points to cover
+
+* Alternative ways of iterating over a container using iterators
+* Adapting or extending standard containers (e.g., writing wrapper types with additional semantics)
+* Discuss the different characteristics and trade-offs of standard containers
+* Common idioms (e.g., find-erase)
+* Usage of end-of-sequence iterators [[Program Design: Iterators - Foundational]][3]
+* [Optional] Using containers together with ranges [[Program Design: Ranges - Foundational]][4]
+
+
+### Advanced
+
+_These are important topics that are not expected to be covered but provide
+guidance where one can continue to investigate this topic in more depth._
+
+* creating your own STL compatible containers from the ground up
+* using containers with non-default allocators
+
+[1]: ../program-design/algorithms.md
+[2]: ../user-defined-types/class-templates.md
+[3]: ../program-design/iterators.md
+[4]: ../program-design/ranges.md

sources/modules/program-design/iterators.md

@@ -0,0 +1,6 @@
+## Program Design: Iterators
+
+_Skeleton descriptions are typeset in italic text,_
+_so please don't remove these descriptions when editing the topic._
+
+This topic is currently under construction and will soon be filled with information :)

sources/modules/program-design/ranges.md

@@ -0,0 +1,6 @@
+## Program Design: Ranges
+
+_Skeleton descriptions are typeset in italic text,_
+_so please don't remove these descriptions when editing the topic._
+
+This topic is currently under construction and will soon be filled with information :)