From 4101af5c2d4db282fe8e6cfcd99bdd255d3a45b5 Mon Sep 17 00:00:00 2001 From: Robert Douglas Date: Tue, 22 Feb 2022 22:12:48 -0600 Subject: [PATCH 1/4] WIP: Straw-man "Headers" for small-group session Issue cplusplus/SG20#3 --- sources/modules/compilation-model/headers.md | 105 +++++++++++++++++++ 1 file changed, 105 insertions(+) create mode 100644 sources/modules/compilation-model/headers.md diff --git a/sources/modules/compilation-model/headers.md b/sources/modules/compilation-model/headers.md new file mode 100644 index 0000000..7f7a51d --- /dev/null +++ b/sources/modules/compilation-model/headers.md @@ -0,0 +1,105 @@ +## Module name: topic name + +_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 Including code through standard library headers + +Main Organize function and class declarations into reusable + files for inclusion into others + +Advanced --- (inlining? templates? hygiene, such as using namespace?) + +------------------------------------------------------------------------ + +### Motivation + +_Why is this important?_ +_Why do we want to learn/teach this topic?_ + +Understanding and using header files allows for common declarations to +be used across multiple files without copying-and-pasting the text. Also, +understanding headers allows re-use of most existing 3rd-party libraries, +as well as the C++ standard library. + +### Topic introduction + +_Very brief introduction to the topic._ + +The contents of header files are injected into a source file to allow +multiple distinct source files to share a single source of common +declarations. + +### Foundational: Including code through standard library headers + +#### Background/Required Knowledge + +A student is able to: + +* Invoke the compiler on a single source file to build an executable + + +#### 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. Include common standard library headers to get access to commonly used declarations + +#### Caveats + +_This section mentions subtle points to understand, like anything resulting in +implementation-defined, unspecified, or undefined behavior._ + +#### Points to cover + +_This section lists important details for each point._ + +* Usage of standard library code requires inclusion of various header files +* Give examples of various header files and when they may be needed for inclusion +* Include links to reference materials for finding out what headers are used for various feature sets + +### Main: Organizing function and class declarations for reuse + +#### Background/Required Knowledge + +* All of the above. +* Define a function and write a separate, matching, declaration +* Distinguish between a declaration and a definition +* Compile multiple translation units and link them together into a single executable + +#### Student outcomes + +A student should be able to: + +1. Create a declaration for an existing function, placed in a separate file +2. Include a header within the same directory +3. Include a header locatable within the compiler's include directories +4. Explain the meaning of the one-definition rule and how it applies to headers +5. Protect a header with include guards and explain why they are necessary + +#### Caveats + +* #pragma is useful, but not standardized and so may not be fully supported on all systems +* Reusing the same include guards may cause confusion. Naming conventions based on file paths can help +* Accidentally putting a definition in a header file may or may not introduce undefined behavior +* Circular dependencies can cause confusion. Care should be taken in identifying such +* + +#### Points to cover + +### 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._ From 370dedd1e2d6ff67cad796172145e6b070a10b7b Mon Sep 17 00:00:00 2001 From: Robert Douglas Date: Wed, 23 Feb 2022 10:57:32 -0600 Subject: [PATCH 2/4] WIP: progress from small group session Issue cplusplus/SG20#3 --- sources/modules/compilation-model/headers.md | 41 +++++++++++++++++--- 1 file changed, 36 insertions(+), 5 deletions(-) diff --git a/sources/modules/compilation-model/headers.md b/sources/modules/compilation-model/headers.md index 7f7a51d..ccc4d81 100644 --- a/sources/modules/compilation-model/headers.md +++ b/sources/modules/compilation-model/headers.md @@ -1,4 +1,4 @@ -## Module name: topic name +## Module name: Headers _Skeleton descriptions are typeset in italic text,_ _so please don't remove these descriptions when editing the topic._ @@ -74,7 +74,7 @@ _This section lists important details for each point._ #### Background/Required Knowledge -* All of the above. +* All of the above * Define a function and write a separate, matching, declaration * Distinguish between a declaration and a definition * Compile multiple translation units and link them together into a single executable @@ -84,14 +84,14 @@ _This section lists important details for each point._ A student should be able to: 1. Create a declaration for an existing function, placed in a separate file -2. Include a header within the same directory -3. Include a header locatable within the compiler's include directories +2. Utilize double-quote inclusion to include a header from the same directory +3. Utilize angular-bracket inclusion to include a header from standard library 4. Explain the meaning of the one-definition rule and how it applies to headers 5. Protect a header with include guards and explain why they are necessary #### Caveats -* #pragma is useful, but not standardized and so may not be fully supported on all systems +* `#pragma once` is useful, but not standardized and so may not be fully supported on all systems * Reusing the same include guards may cause confusion. Naming conventions based on file paths can help * Accidentally putting a definition in a header file may or may not introduce undefined behavior * Circular dependencies can cause confusion. Care should be taken in identifying such @@ -99,7 +99,38 @@ A student should be able to: #### Points to cover +* Angular bracket inclusion goes to the system/compiler path +* Double quotes inclusion uses just relative paths + ### 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._ + +Templates in headers? +Classes in headers? +Macros in headers? +Modules as replacement? +Issues with specifying default arguments in headers? + + +#### Background/Required Knowledge + +* All of the above + +#### Student outcomes + +A student should be able to: + +1. Utilize angular-bracket inclusion and compiler flags to include headers from non-standard paths +2. Identify trade-offs of aggressiveness of putting declarations in a header file without known consumer + +#### Caveats + +_This section mentions subtle points to understand, like anything resulting in +implementation-defined, unspecified, or undefined behavior._ + +#### Points to cover + +_This section lists important details for each point._ + From b7d8028962cea088032c5def3d428c97da2b9f5e Mon Sep 17 00:00:00 2001 From: rwdougla Date: Wed, 23 Mar 2022 11:01:47 -0500 Subject: [PATCH 3/4] Progress from March US Small Group session Would like to get cross-references in advance section to other modules which are coupled to headers, such as classes, templates, modules, etc. --- sources/modules/compilation-model/headers.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/sources/modules/compilation-model/headers.md b/sources/modules/compilation-model/headers.md index ccc4d81..31be5d8 100644 --- a/sources/modules/compilation-model/headers.md +++ b/sources/modules/compilation-model/headers.md @@ -13,8 +13,8 @@ Level Objective ----------------- ------------------------------------------------------ Foundational Including code through standard library headers -Main Organize function and class declarations into reusable - files for inclusion into others +Main Write headers to support separate compilation and code + organization Advanced --- (inlining? templates? hygiene, such as using namespace?) @@ -55,7 +55,7 @@ _Max 5 items._ A student should be able to: -1. Include common standard library headers to get access to commonly used declarations +1. Include common standard library headers to get access to standard library features #### Caveats @@ -69,9 +69,12 @@ _This section lists important details for each point._ * Usage of standard library code requires inclusion of various header files * Give examples of various header files and when they may be needed for inclusion * Include links to reference materials for finding out what headers are used for various feature sets +* When using standard library facilities, can either use `using std::vector; vector v;`, or `std::vector v;`, or `using namespace std; vector v;`, though modern practice strongly discourages invoking `using namespace std;` ### Main: Organizing function and class declarations for reuse +_Description: Write headers to support separate compilation and code organization_ + #### Background/Required Knowledge * All of the above @@ -107,6 +110,7 @@ A student should be able to: _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._ +Header-only libraries? Templates in headers? Classes in headers? Macros in headers? From 5aff11cdfbbacecaac7c9d7a2d97285b3bd49556 Mon Sep 17 00:00:00 2001 From: rwdougla Date: Wed, 7 Dec 2022 12:56:15 -0600 Subject: [PATCH 4/4] Update headers.md feeling of small-group was to omit advanced section, as each advanced topic seemed more relevant to a different module --- sources/modules/compilation-model/headers.md | 36 +------------------- 1 file changed, 1 insertion(+), 35 deletions(-) diff --git a/sources/modules/compilation-model/headers.md b/sources/modules/compilation-model/headers.md index 31be5d8..a1ecffb 100644 --- a/sources/modules/compilation-model/headers.md +++ b/sources/modules/compilation-model/headers.md @@ -16,7 +16,7 @@ Foundational Including code through standard library headers Main Write headers to support separate compilation and code organization -Advanced --- (inlining? templates? hygiene, such as using namespace?) +Advanced --- ------------------------------------------------------------------------ @@ -98,43 +98,9 @@ A student should be able to: * Reusing the same include guards may cause confusion. Naming conventions based on file paths can help * Accidentally putting a definition in a header file may or may not introduce undefined behavior * Circular dependencies can cause confusion. Care should be taken in identifying such -* #### Points to cover * Angular bracket inclusion goes to the system/compiler path * Double quotes inclusion uses just relative paths -### 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._ - -Header-only libraries? -Templates in headers? -Classes in headers? -Macros in headers? -Modules as replacement? -Issues with specifying default arguments in headers? - - -#### Background/Required Knowledge - -* All of the above - -#### Student outcomes - -A student should be able to: - -1. Utilize angular-bracket inclusion and compiler flags to include headers from non-standard paths -2. Identify trade-offs of aggressiveness of putting declarations in a header file without known consumer - -#### Caveats - -_This section mentions subtle points to understand, like anything resulting in -implementation-defined, unspecified, or undefined behavior._ - -#### Points to cover - -_This section lists important details for each point._ -