C++ Logo


Advanced search

Feedback from SG20 Topic Meeting for "Headers" (2022-02-23)

From: Michael Adams <frodo_at_[hidden]>
Date: Wed, 2 Mar 2022 16:02:26 -0800 (PST)
Hi Everyone,

On February 23, the "North-America timezone" subgroup of SG20 met to
develop a preliminary draft of the content for the "Headers" topic under
the "Compilation Model" module in the C++ teaching guidelines document.
The meeting participants consisted of Robert Douglas, Victor Eijkhout,
and myself. The latest published version of the guidelines document
(which does not include the "Headers" topic) is available at:


The work on the "Headers" topic is associated with the following pull
request on GitHub:


During the above meeting, we encountered a number of issues that were
somewhat detrimental to making fast progress on developing the content
for the "Headers" topic. Since these issues are likely to impact others
who are trying to contribute content for other topics, we decided to
provide some feedback (via the SG20 mailing list) based on our experiences
during the above meeting. In what follows, I have tried my best to
capture the sentiments expressed in this meeting.

The most significant difficulty that was faced is probably best summarized
as a lack of clarity about exactly how the topic being developed would
fit with the other content that is to be later developed. This led to
questions like the following:

   1. To what extent are dependencies acceptable for a given topic
      being covered? What other topics should a particular topic be
      allowed to depend on? Should there be guidelines for deciding
      what level of dependencies to allow? The answers to these
      questions are not clear. At one extreme, having a very high
      number of dependencies will greatly increase the number of circular
      references in the guidelines document and also likely make the final
      document much more difficult for end users to navigate. At the other
      extreme (i.e., very few or no dependencies), one might be too
      constrained in what can be discussed due to the need to avoid
      introducing additional dependencies.

   2. What is the true intended scope of given topic being developed?
      For example, in the case of our meeting, the topic was "Headers".
      The topic of "Headers" could be interpreted as having either a very
      narrow or very broad scope. In the case of a more narrow scope,
      the focus might be more on the preprocessor include directive itself
      and what types of source code are appropriate for placement in a header
      (without relying on knowledge of classes, templates, modules, or other
      such language features). With a broader scope, the focus could start
      to talk about the many interactions between headers and other language
      features such as classes, templates, modules, and so on. As the scope of
      topics are broadened, the amount of redundancy and overlap between
      topics also grows significantly, which will likely make navigating
      the document more difficult for the end user as well as making the
      document more difficult to maintain by SG20 over time.

   3. Is it implicit that higher level coverage of a topic requires coverage
      of the topic at the lower levels as a prerequisite? For example,
      when covering a topic like "Headers" at the advanced level, it is
      implicitly assumed that the student already has seen coverage at
      the foundational and main levels? If this is implicit, this eliminates
      the need (in the text for a topic) to repeatedly state that the
      required background for level X includes the background for level
      Y for each Y < X.

Note that items 1 and 2 above are very much interdependent as the scope
of coverage will also greatly impact the number of dependencies.

It was felt, during our meeting, that a discussion of the above issues
within the SG20 group as as whole would be highly beneficial. In order
for this project to be successful, we need to minimize barriers to those
who might be interested in preparing content, and some of the issues
identified above may serve as barriers to contributors (including
the members of SG20 itself).

Just before closing, I would like to make a brief suggestion, which
is based solely on my own personal opinion and may or may not reflect
the opinion of Robert and Victor. In light of the above, my personal
feeling is that it would be highly beneficial to take a closer look at
the guidelines document from the top down. This might entail something
like the following:

   1. Identify the areas of C++ teaching that are not well covered
      (or have no coverage) by the modules/topics identified in the current
      guidelines document, and possibly perform some further refinement
      of the existing modules/topics.

   2. Try to sketch out the intended scope of each of the modules/topics.

In other words, I am advocating that we spend a little more time on the
planning of the overall document structure before investing too much more
effort on the finer details of developing individual topics. By doing
something like this, we would gain a much better understanding of what all
will be covered in the final guidelines document and the scope of coverage
for the various modules/topics. This would help to address the issues
identified earlier in this email. In turn, this would help to remove
obstacles to those who would like to contribute content for the various
topics in the guidelines document. Also, as an important side benefit
of this additional planning, the various parts of the document are
much more likely to fit together in the end.

[Note to Robert Douglas and Victor Eijkhout: I have tried my best to
capture the various sentiments expressed in our recent meeting. If I have
omitted anything important or not clearly/accurately conveyed some aspects
of what was discussed, please jump in and correct me.]


Michael Adams, Associate Professor, Ph.D., P.Eng., IEEE Senior Member
Dept. of Electrical and Computer Engineering, University of Victoria
PO Box 1700 STN CSC, Victoria, BC, V8W 2Y2, CANADA
E-mail: mdadams_at_[hidden], Web: http://www.ece.uvic.ca/~mdadams

Received on 2022-03-03 00:02:42