Headers module

sources/modules/compilation-model/headers.md

@@ -0,0 +1,108 @@
+## C++ compilation model: Headers {#headers}
+
+_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              Write headers to support separate compilation and code
+                  organization
+
+Advanced          ---
+
+------------------------------------------------------------------------
+
+### 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 {#headers-found}
+
+#### 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 standard library features
+
+#### Caveats
+
+_This section mentions subtle points to understand, like anything resulting in
+implementation-defined, unspecified, or undefined behavior._
+
+* The include directly actually copies the header file into the file it is included in.
+
+#### 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
+* When using standard library facilities, can either use `using std::vector; vector<int> v;`, or `std::vector<int> v;`, or `using namespace std; vector<int> v;`, though modern practice strongly discourages invoking `using namespace std;`
+
+### Main: Organizing function and class declarations for reuse  {#headers-main}
+
+_Description: Write headers to support separate compilation and code organization_
+
+#### 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. 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 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
+
+#### Points to cover
+
+* Angular bracket inclusion goes to the system/compiler path
+* Double quotes inclusion uses just relative paths
+