is invariant under local rescalings of the metric when $\Lambda$ is a surface,
as is the case here.

Further simplification of the obstruction can be obtained by noting that in
the setting of $d-k=2$, $\hskip 1.13809pt\mathring{\rm{II}}{}_{\alpha}$ is a
trace-free symmetric 2x2 matrix. It follows from the Cayley–Hamilton theorem
that $\hskip 1.13809pt\mathring{\rm{II}}{}^{a}_{b\alpha}\hskip
1.13809pt\mathring{\rm{II}}{}^{b}_{c\alpha}$ is proportional to the identity
matrix, and so the $\hskip 1.13809pt\mathring{\rm{II}}{}^{3}$ term vanishes,
leaving us with

$F^{(3)}_{\alpha\gamma\gamma\rho\rho}\stackrel{{\scriptstyle\Lambda}}{{=}}-\tfrac{d-2}{6}L_{ab}\hskip
1.13809pt\mathring{\rm{II}}{}^{ab}_{\alpha}-\tfrac{1}{3}\hskip
1.13809pt\mathring{\rm{II}}{}^{bc}_{\alpha}\bar{g}^{ad}W_{abcd}-\tfrac{d-2}{6}{{\bf\rm
IV}{\hskip 0.56905pt}}{}_{\alpha}+\text{ terms containing }\beta\,.$

Observe that when $d=3$ and $k=1$, all of $W$, ${{\bf\rm IV}{\hskip
0.56905pt}}{}_{\alpha}$, and $\beta$ vanish. So for a surface embedded in a
3-volume, we have that

$F^{(3)}\stackrel{{\scriptstyle\Lambda}}{{=}}-\tfrac{1}{6}\left(\bar{\nabla}_{a}\bar{\nabla}_{b}+P^{\top}_{ab}+H\hskip
1.13809pt\mathring{\rm{II}}{}_{ab}\right)\hskip
1.13809pt\mathring{\rm{II}}{}^{ab}\,,$

which matches [10] the famous Willmore invariant [35] up to a factor of $1/2$.

######  Remark 8.3.

An interesting question is whether this Willmore invariant is variational for
higher codimension surface embeddings, and if so, what energy functional it
comes from. We leave this for future work.

##  9\. The Extension Problem

Recall from the previous section that it is sometimes useful to extend
functions (or arrays thereof) on $\Lambda$ to a tubular neighborhood, at least
formally. To that end, we consider these so-called extension problems in both
the Riemannian and conformal settings for submanifold embeddings. Such
problems are of more general interest, see [15]. The Riemannian problem can be
stated as

######  Problem 9.1.

Let $\bar{f}\in C^{\infty}\Lambda$ and let $s_{\alpha}$ be a canonical
defining map for $\Lambda^{d-k}\hookrightarrow(M^{d},g)$. Find a formal power
series to as high order as possible for $f\in C^{\infty}M$ solving

$\nabla_{n_{\alpha}}f=0\,,\qquad f|_{\Lambda}=\bar{f}\,.$

However, unlike the hypersurface case, we will find that such a problem can
not, in general, be solved. Trivially, when $\bar{f}$ is constant, we may
extend uniquely so that $f$ is constant as well. Of interest are the cases
where $f$ is non-constant. Then, two modifiations can be made that allow
solutions. We will handle these two modifications first, and then we will
consider the conformal extension problem.

###  9.1. The Symmetric Extension Problem

Rather than solving Problem 9.1, we instead weaken the constraint equations,
so that the problem of interest takes the following form:

######  Problem 9.2.

Let $\bar{f}\in C^{\infty}\Lambda$ and let $s_{\alpha}$ be a canonical
defining map for $\Lambda^{d-k}\hookrightarrow(M^{d},g)$. For a given
$m\in\mathbb{Z}_{\geqslant 1}$, find $f\in C^{\infty}M$ satisfying
$f|_{\Lambda}=\bar{f}$ and

$\nabla_{n_{\alpha}}f\stackrel{{\scriptstyle\Lambda}}{{=}}0\,,\qquad
n^{a_{1}a_{2}}_{(\alpha_{1}\alpha_{2})}\nabla_{a_{1}a_{2}}f\stackrel{{\scriptstyle\Lambda}}{{=}}0\,,\qquad\ldots\,,\qquad
n^{a_{1}\cdots a_{m+1}}_{(\alpha_{1}\cdots\alpha_{m})}\nabla_{a_{1}\cdots
a_{m}}f\stackrel{{\scriptstyle\Lambda}}{{=}}0.$

In the above and going forward, $n^{a_{1}\cdots
a_{n}}_{\alpha_{1}\cdots\alpha_{n}}:=n^{a_{1}}_{\alpha_{1}}\cdots
n^{a_{n}}_{\alpha_{n}}$ and similarly $\nabla_{a_{1}\cdots
a_{n}}:=\nabla_{a_{1}}\cdots\nabla_{a_{n}}$. To solve this problem requires a
series of technical results.

######  Lemma 9.3.

Let $\Lambda\hookrightarrow(M,g)$ be a Riemannian submanifold embedding with a
defining map $s_{\alpha}$ and let $m\in\mathbb{Z}_{\geqslant 2}$. Suppose that
the defining map satisfies
$G_{\alpha\beta}=\delta_{\alpha\beta}+\mathcal{O}(s^{2})$ and

$n^{a_{1}\cdots a_{n-1}}_{(\alpha_{1}\cdots\alpha_{n-1}}\nabla_{a_{1}\cdots
a_{n-1}b}G_{\gamma\delta)}\stackrel{{\scriptstyle\Lambda}}{{=}}0\stackrel{{\scriptstyle\Lambda}}{{=}}n^{a_{1}\cdots
a_{n}}_{(\alpha_{1}\cdots\alpha_{n}}\nabla_{a_{1}\cdots
a_{n}}G_{\gamma)\delta}$

for all $2\leqslant n\leqslant m$. Then, for each $1\leqslant p\leqslant m+1$,
we have that

$n^{a_{1}\cdots a_{p}}_{(\alpha_{1}\cdots\alpha_{p})}\nabla_{a_{1}\cdots
a_{p}}s_{\beta}\stackrel{{\scriptstyle\Lambda}}{{=}}\begin{cases}0&p\neq 1\\\
\delta_{\alpha_{1}\beta}&p=1\,.\end{cases}$

###### Proof.

The case where $p=1$ follows trivially. We consider the case where $p\geqslant
2$ and prove via induction. When $p=2$, the identity reduces to the fact that
$n\cdot\beta\stackrel{{\scriptstyle\Lambda}}{{=}}0$.

Now fix $p$, and suppose that the identity holds for all $k\leqslant
p\leqslant m$. We wish to show that the identity holds for $k=p+1$. We then
compute:

$\displaystyle
n^{a_{p}}_{\alpha_{p}}n^{a_{p+1}}_{\alpha_{p+1}}\nabla^{p-1}\nabla_{a_{p}}\nabla_{a_{p+1}}s_{\beta}\stackrel{{\scriptstyle\Lambda}}{{=}}$
$\displaystyle
n^{a_{p}}_{\alpha_{p}}\nabla^{p-1}\nabla_{a_{p}}G_{\alpha_{p+1}\beta}-n^{a_{p}}_{\alpha_{p}}n^{a_{p+1}}_{\beta}\nabla^{p-1}\nabla_{a_{p}}n_{a_{p+1}\alpha_{p+1}}$
$\displaystyle\stackrel{{\scriptstyle\Lambda}}{{=}}$ $\displaystyle
n^{a_{p}}_{\alpha_{p}}\nabla^{p-1}\nabla_{a_{p}}G_{\alpha_{p+1}\beta}-n^{a_{p}}_{\alpha_{p}}n^{a_{p+1}}_{\beta}\nabla^{p-1}\nabla_{a_{p+1}}n_{a_{p}\alpha_{p+1}}$
$\displaystyle\stackrel{{\scriptstyle\Lambda}}{{=}}$ $\displaystyle
n^{a_{p}}_{\alpha_{p}}\nabla^{p-1}\nabla_{a_{p}}G_{\alpha_{p+1}\beta}-\tfrac{1}{2}n^{a_{p+1}}_{\beta}\nabla^{p-1}\nabla_{a_{p+1}}G_{\alpha_{p}\alpha_{p+1}}$
$\displaystyle\stackrel{{\scriptstyle\Lambda}}{{=}}$ $\displaystyle 0\,.$

The first identity holds via the Leibniz identity and the induction
hypothesis: moving $n$ past any number of covariant derivatives costs
additional products, each of which has strictly fewer than $p+1$ symmetric
normal derivatives on $s$. By the induction hypothesis, these additional terms
vanish. The third equality follows by the same observation, as well as by
noting that all such expressions are symmetric in $\alpha_{p}$ and
$\alpha_{p+1}$. The final identity follows by the proposition hypothesis. The
lemma follows. ∎

######  Corollary 9.4.

Let $\Lambda\hookrightarrow(M,g)$ be a Riemannian submanifold embedding with a
defining map $s_{\alpha}$ and let $m\in\mathbb{Z}_{\geqslant 2}$. Suppose that
the defining map satisfies
$G_{\alpha\beta}=\delta_{\alpha\beta}+\mathcal{O}(s^{2})$ and

$n^{a_{1}\cdots a_{n-1}}_{(\alpha_{1}\cdots\alpha_{n-1}}\nabla_{a_{1}\cdots
a_{n-1}b}G_{\gamma\delta)}\stackrel{{\scriptstyle\Lambda}}{{=}}0\stackrel{{\scriptstyle\Lambda}}{{=}}n^{a_{1}\cdots
a_{n}}_{(\alpha_{1}\cdots\alpha_{n}}\nabla_{a_{1}\cdots
a_{n}}G_{\gamma)\delta}$

for all $2\leqslant n\leqslant m$. Then, for every $1\leqslant p\leqslant m$,
we have that

$n^{a_{1}\cdots a_{p}}_{(\alpha_{1}\cdots\alpha_{p}}\nabla_{a_{1}\cdots
a_{p}}n^{b}_{\beta)}\stackrel{{\scriptstyle\Lambda}}{{=}}0\,.$

###### Proof.

We prove by induction. For $p=1$, this follows simply because
$n^{a}_{(\alpha}\nabla_{a}n^{b}_{\beta)}\stackrel{{\scriptstyle\Lambda}}{{=}}\beta^{b}_{(\alpha\beta)}\stackrel{{\scriptstyle\Lambda}}{{=}}0$.
Now suppose the identity holds for all $k\leqslant p\leqslant m-1$. Now
consider the case where $k=p+1$ and compute:

$\displaystyle n^{a_{1}\cdots
a_{p}}_{(\alpha_{1}\cdots\alpha_{p}}n^{a_{p+1}}_{\alpha_{p+1}}\nabla^{p}\nabla_{a_{p+1}}n^{b}_{\beta)}\stackrel{{\scriptstyle\Lambda}}{{=}}$
$\displaystyle n^{a_{1}\cdots
a_{p}}_{(\alpha_{1}\cdots\alpha_{p}}n^{a_{p+1}}_{\alpha_{p+1}}\nabla^{p}\nabla^{b}n_{a_{p+1}\beta)}$
$\displaystyle\stackrel{{\scriptstyle\Lambda}}{{=}}$
$\displaystyle\tfrac{1}{2}n^{a_{1}\cdots
a_{p}}_{(\alpha_{1}\cdots\alpha_{p}}\nabla^{p}\nabla^{b}G_{\alpha_{p+1}\beta)}$
$\displaystyle\stackrel{{\scriptstyle\Lambda}}{{=}}$ $\displaystyle 0\,.$

The second identity follows by commuting normal vectors to the right, which
costs nothing via the Leibniz rule according to Lemma 9.3. The third identity
follows from the hypothesis. ∎

######  Corollary 9.5.

Let $\Lambda\hookrightarrow(M,g)$ be a Riemannian submanifold embedding with a
defining map $s_{\alpha}$ and let $m\in\mathbb{Z}_{\geqslant 2}$. Suppose that
the defining map satisfies
$G_{\alpha\beta}=\delta_{\alpha\beta}+\mathcal{O}(s^{2})$ and

$n^{a_{1}\cdots a_{n-1}}_{(\alpha_{1}\cdots\alpha_{n-1}}\nabla_{a_{1}\cdots
a_{n-1}b}G_{\gamma\delta)}\stackrel{{\scriptstyle\Lambda}}{{=}}0\stackrel{{\scriptstyle\Lambda}}{{=}}n^{a_{1}\cdots
a_{n}}_{(\alpha_{1}\cdots\alpha_{n}}\nabla_{a_{1}\cdots
a_{n}}G_{\gamma)\delta}$

for all $2\leqslant n\leqslant m$. Then, for each $1\leqslant p\leqslant m+1$
and $1\leqslant\ell$, we have that

$n^{a_{1}\cdots a_{p}}_{(\alpha_{1}\cdots\alpha_{p})}\nabla_{a_{1}\cdots
a_{p}}(s_{\beta_{1}}\cdots s_{\beta_{\ell}}n^{b_{1}}_{\beta_{1}}\cdots
n^{b_{\ell}}_{\beta_{\ell}})\stackrel{{\scriptstyle\Lambda}}{{=}}\begin{cases}0&p\neq\ell\\\
p!n^{b_{1}}_{(\alpha_{1}}\cdots n^{b_{p}}_{\alpha_{p})}&p=\ell\,.\end{cases}$

###### Proof.

For $p<\ell$, the result is trivial. Furthermore, for $p=\ell$, the result
follows trivially by noting that each covariant derivative must act on a
unique $s_{\beta}$, yielding $n_{\alpha}\cdot n_{\beta}=\delta_{\alpha\beta}$.

Finally, consider the case where $p>\ell$. Then, following Lemma 9.3, we may
only have one derivative acting on each $s$. Thus, in each term in the Leibniz
expansion there exists at least one normal vector that is acted upon by more
than one normal derivative. However, note that each normal vector has had its
Greek index $\beta_{i}$ has been replaced by a Greek index $\alpha_{j}$ for
some $j$ as a consequence of the action of the normal derivatives on $s$.
Hence, we are examining terms of the form present in Corollary 9.4. Therefore,
all such terms vanish and the result follows. ∎

We require one more technical lemma:

######  Lemma 9.6.

Let $\Lambda^{d-k}\hookrightarrow(M^{d},g)$ be parallelized by
$\\{n_{\alpha}\\}$ and let $s_{\alpha}$ be the corresponding canonical
defining map. Then,

$n^{a_{1}\cdots a_{n-1}}_{(\alpha_{1}\cdots\alpha_{n-1}}\nabla_{a_{1}\cdots
a_{n-1}b}G_{\gamma\delta)}\stackrel{{\scriptstyle\Lambda}}{{=}}0\stackrel{{\scriptstyle\Lambda}}{{=}}n^{a_{1}\cdots
a_{n}}_{(\alpha_{1}\cdots\alpha_{n}}\nabla_{a_{1}\cdots
a_{n}}G_{\gamma)\delta}$

for each $n\in\mathbb{Z}_{\geqslant 1}$.

###### Proof.

We will prove this by analyzing a fixed term $F^{(i)}s^{i}$ in the expansion
of $G_{\alpha\beta}$ and using induction on $n$. The base case ($n=1$)
trivially holds because $G=\delta+\mathcal{O}(s^{2})$. Now fix some
$n\geqslant 2$, and suppose that for each $1\leqslant j\leqslant n$, we have
that

$n^{a_{1}\cdots a_{j-1}}_{(\alpha_{1}\cdots\alpha_{j-1}}\nabla_{a_{1}\cdots
a_{j-1}b}G_{\gamma\delta)}\stackrel{{\scriptstyle\Lambda}}{{=}}0\stackrel{{\scriptstyle\Lambda}}{{=}}n^{a_{1}a_{2}\cdots
a_{j}}_{(\alpha_{1}\alpha_{2}\cdots\alpha_{j}}\nabla_{a_{1}\cdots
a_{j}}G_{\gamma)\delta}$

We would like to show that this identity holds in the case where $j=n+1$ as
well. To do so, it is sufficient to show that, for each $i$, we have that

(9.1) $\displaystyle n^{a_{1}\cdots
a_{n+1}}_{(\alpha_{1}\cdots\alpha_{n+1}}\nabla_{a_{1}\cdots
a_{n+1}}(F^{(i)}_{\gamma)\delta\gamma_{1}\cdots\gamma_{i}}s_{\gamma_{1}}\cdots
s_{\gamma_{i}})\stackrel{{\scriptstyle\Lambda}}{{=}}0\stackrel{{\scriptstyle\Lambda}}{{=}}n^{a_{1}\cdots
a_{n}}_{(\alpha_{1}\cdots\alpha_{n}}\nabla_{a_{1}\cdots
a_{n}b}(F^{(i)}_{\gamma\delta)\gamma_{1}\cdots\gamma_{i}}s_{\gamma_{1}}\cdots
s_{\gamma_{i}})\,.$

Certainly, for $n+1<i$, we find that the identity holds as
$\nabla^{n+1}s^{i}\stackrel{{\scriptstyle\Lambda}}{{=}}0$. If $n+1=i$, then we
must compute the appropriate symmetrization over $i+1$ indices of $F^{(i)}$.
However, for either symmetrization, because $F^{(i)}$ occupies a generalized
window representation according to Theorem 4.1, this term necessarily
vanishes.

Finally, consider the case where $n+1>i$. The leading derivative term on
$F^{(i)}$ takes the form $\nabla^{n-i+1}F^{(i)}$. However, such a term
vanishes because $F^{(i)}$ (even away from $\Lambda$) occupies the generalized
window representation, and this term symmetrizes over $i+1$ indices of
$F^{(i)}$. On the other hand, subleading terms must be considered: those terms
of the form $(\nabla^{\ell}s^{i})\nabla^{n+1-\ell}F^{(i)}$, where $\ell>i$.
Note that at least one $s$ is differentiated twice, but no $s$ is
differentiated more than $n-i+2$ times. Note that via the induction
hypothesis, we may use both Lemma 9.3 and Corollary 9.4 to examine these
terms, as $n-i+2\leqslant n$ (because $i\geqslant 2$).

Now, consider the term on the left hand side of Equation (9.1). All such terms
of the form $(\nabla^{\ell}s^{i})\nabla^{n+1-\ell}F^{(i)}$ for this term
contain at least one multiplicand that vanishes due to Lemma 9.3. Thus, we
need only consider the right hand side of Equation (9.1).

In that case, there are two types of terms in a Leibniz expansion that must be
examined. The first type of term is one that contains a multiplicand of the
form to which Lemma 9.3 is applicable. These terms must therefore vanish.
Hence, we must only examine terms of the second type, namely those terms where
each of $i-1$ factors of $s$ are acted upon by $\nabla_{n}$ exactly once, and
one remaining $s$ is acted upon by $\nabla_{n}^{\ell-i}\nabla_{b}$:

$(n^{a_{1}\cdots
a_{\ell-i}}_{(\alpha_{1}\cdots\alpha_{\ell-i}}\nabla_{a_{1}\cdots
a_{\ell-i}b}s_{|\gamma_{1}|})\nabla^{n+1-\ell}F^{(i)}_{\gamma\delta)\gamma_{1}\alpha_{1}\cdots\alpha_{\ell-1}}\,.$

But note that here $F^{(i)}$ is symmetrized over $i+1$ indices, and therefore
must vanish.

Having shown that all terms in a Leibniz expansion for both the left and right
hand sides of Equation (9.1) vanish for all $i$, we have that the lemma
follows. ∎

We are now equipped to solve Problem 9.2:

######  Theorem 9.7.

Let $\Lambda\hookrightarrow(M,g)$ be a parallelized Riemannian submanifold
embedding with a canonical defining map $s_{\alpha}$, let $\bar{f}\in
C^{\infty}\Lambda$, and let $m\in\mathbb{Z}_{\geqslant 2}$. Then, there exists
a unique $\tilde{f}\in C^{\infty}M$ modulo terms of order $m+2$ with
$\tilde{f}|_{\Lambda}=\bar{f}$ satisfying

$\nabla_{n_{\alpha}}\tilde{f}\stackrel{{\scriptstyle\Lambda}}{{=}}0\,,\qquad
n^{a_{1}a_{2}}_{(\alpha_{1}\alpha_{2})}\nabla_{a_{1}a_{2}}\tilde{f}\stackrel{{\scriptstyle\Lambda}}{{=}}0\,,\qquad\ldots\,,\qquad
n^{a_{1}\cdots a_{m+1}}_{(\alpha_{1}\cdots\alpha_{m+1})}\nabla_{a_{1}\cdots
a_{m+1}}\tilde{f}\stackrel{{\scriptstyle\Lambda}}{{=}}0.$

###### Proof.

We begin by fixing $m$. Then, let $f\in C^{\infty}M$ be any function
satisfying $f|_{\Lambda}=\bar{f}$ and define

(9.2)
$\displaystyle\tilde{f}:=f-s_{\beta_{1}}n^{b_{1}}_{\beta_{1}}\nabla_{b_{1}}f+\tfrac{1}{2}s_{\beta_{1}}s_{\beta_{2}}n^{b_{1}}_{\beta_{1}}n^{b_{2}}_{\beta_{2}}\nabla_{b_{1}}\nabla_{b_{2}}f-\tfrac{1}{6}s_{\beta_{1}}s_{\beta_{2}}s_{\beta_{3}}n^{b_{1}}_{\beta_{1}}n^{b_{2}}_{\beta_{2}}n^{b_{3}}_{\beta_{3}}\nabla_{b_{1}}\nabla_{b_{2}}\nabla_{b_{3}}f+\cdots\,.$

Now, we would like to show that this ansatz satisfies the conditions of the
theorem. In particular, we must check that

$n^{a_{1}\cdots a_{q}}_{(\alpha_{1}\cdots\alpha_{q})}\nabla_{a_{1}\cdots
a_{q}}\tilde{f}\,,$

vanishes for all $1\leqslant q\leqslant m+1$. Now we examine a generic term
from $\tilde{f}$, say the term containing $s^{\ell}$. That is, consider

$\tfrac{(-1)^{\ell}}{\ell!}n^{a_{1}\cdots
a_{q}}_{(\alpha_{1}\cdots\alpha_{q})}\nabla_{a_{1}\cdots
a_{q}}(s_{\beta_{1}}\cdots s_{\beta_{\ell}}n^{b_{1}}_{\beta_{1}}\cdots
n^{b_{\ell}}_{\beta_{\ell}}\nabla_{b_{1}\cdots b_{\ell}}f)\,.$

Trivially this expression vanishes when $q<\ell$. When $q\geqslant\ell$, we
may rewrite this expression as

$\tfrac{(-1)^{\ell}}{\ell!}n^{a_{1}\cdots
a_{q}}_{(\alpha_{1}\cdots\alpha_{q})}\sum_{r=0}^{q}{q\choose
r}(\nabla_{a_{1}\cdots a_{r}}s_{\beta_{1}}\cdots
s_{\beta_{\ell}}n^{b_{1}}_{\beta_{1}}\cdots
n^{b_{\ell}}_{\beta_{\ell}})(\nabla_{a_{r+1}\cdots a_{q}}\nabla_{b_{1}\cdots
b_{\ell}}f)\,.$

Now from Lemma 9.6, we have that the hypothesis of Corollary 9.5 holds for
every $m$. Furthermore, as $q\geqslant\ell$, we have that this sum includes
the case where $r=\ell$. Thus, we have that

$\tfrac{(-1)^{\ell}}{\ell!}n^{a_{1}\cdots
a_{q}}_{(\alpha_{1}\cdots\alpha_{q})}\sum_{r=0}^{q}{q\choose
r}(\nabla_{a_{1}\cdots a_{r}}s_{\beta_{1}}\cdots
s_{\beta_{\ell}}n^{b_{1}}_{\beta_{1}}\cdots
n^{b_{\ell}}_{\beta_{\ell}})(\nabla_{a_{r+1}\cdots a_{q}}\nabla_{b_{1}\cdots
b_{\ell}}f)\\\ =(-1)^{\ell}{q\choose\ell}n^{a_{1}\cdots
a_{q}}_{(\alpha_{1}\cdots\alpha_{q})}\nabla_{a_{1}\cdots a_{q}}f\,.$

It follows then that

$n^{a_{1}\cdots a_{q}}_{(\alpha_{1}\cdots\alpha_{q})}\nabla_{a_{1}\cdots
a_{q}}\tilde{f}\stackrel{{\scriptstyle\Lambda}}{{=}}\left(\sum_{\ell=0}^{q}(-1)^{\ell}{q\choose\ell}\right)n^{a_{1}\cdots
a_{q}}_{(\alpha_{1}\cdots\alpha_{q})}\nabla_{a_{1}\cdots
a_{q}}f\stackrel{{\scriptstyle\Lambda}}{{=}}0\,,$

by the binomial theorem. Thus $\tilde{f}$ satisfies the required derivative
constraints.

To complete the proof, it suffices to check that if we had initially chosen a
distinct $f^{\prime}\in C^{\infty}M$ and built the ansatz accordingly, we find
that $\tilde{f}^{\prime}-\tilde{f}=s_{\alpha_{1}}\cdots
s_{\alpha_{m+2}}O_{\alpha_{1}\cdots\alpha_{m+2}}$, for some smooth
$O_{\alpha_{1}\cdots\alpha_{m+2}}$. Now, note that because
$f^{\prime}|_{\Lambda}\stackrel{{\scriptstyle\Lambda}}{{=}}\bar{f}$, we must
have that $f^{\prime}-f=s_{\alpha}T_{\alpha}$ for some smooth $T_{\alpha}$. We
must check that the first $m+1$ symmetric normal derivatives of this
difference vanishes. However, from the above computation it is clear that
$m+1$ symmetric normal derivatives of $\widetilde{(s_{\alpha}T_{\alpha})}$
vanishes. And as the ansatz operator is linear, this shows that the difference
of the ansatze must vanish to sufficiently high order. This completes the
proof.

∎

######  Remark 9.8.

Note that the condition in the display of Theorem 9.7 is independent of the
choice of parallelization, and hence by uniqueness of the result, so is the
extension.

###  9.2. The Restricted Extension Problem

Alternatively, we may hope that we can extend $\bar{f}$ to force many normal
derivatives to vanish if certain constraints are placed on the embedding map
$\Lambda^{d-k}\hookrightarrow(M^{d},g)$. The problem we wish to solve is as
follows:

######  Problem 9.9.

Let $\bar{f}\in C^{\infty}\Lambda$, let $s_{\alpha}$ be a canonical defining
map for $\Lambda^{d-k}\hookrightarrow(M^{d},g)$. Find a formal power series to
as high order as possible for $f\in C^{\infty}M$ solving

$\nabla_{n_{\alpha}}f=0\,,\qquad f|_{\Lambda}=\bar{f}\,.$

We find that, contrary to the case of hypersurface embeddings, which have
solutions to all orders by the Picard–Lindelöf theorem, this extension problem
encounters an obstruction. To see this, we proceed order by order.

Suppose that $f_{0}\in C^{\infty}M$ is any function such that
$f_{0}|_{\Lambda}=\bar{f}$, and let
$f_{1}=f_{0}-s_{\alpha}\nabla_{n_{\alpha}}f_{0}$. Then, a straightforward
computation shows that

$\nabla_{n_{\alpha}}f_{1}=F_{\alpha\beta}s_{\beta}\,,$

for some array of functions $F$. Now suppose that we wish to proceed to a
higher order by writing

$f_{2}=f_{1}+s_{\alpha}s_{\beta}A_{\alpha\beta}\,.$

Observe that here, we may consider only $A_{\alpha\beta}=A_{(\alpha\beta)}$.
If $f_{2}$ is to solve Problem 9.9 to second order, then we must have that
$A\propto F$. However, $F$ is not necessarily symmetric. While we can choose
$A$ so that $F_{(\alpha\beta)}$ is cancelled, we cannot do the same for
$F_{[\alpha\beta]}$. In fact, this is our first obstruction, and it can be
calculated:

$\displaystyle F_{[\alpha\beta]}$
$\displaystyle\stackrel{{\scriptstyle\Lambda}}{{=}}-\nabla_{n_{[\alpha}}\nabla_{n_{\beta]}}f_{1}$
$\displaystyle\stackrel{{\scriptstyle\Lambda}}{{=}}-n^{a}_{[\alpha}(\nabla_{a}n^{b}_{\beta]})\nabla_{b}f_{1}-n^{a}_{\alpha}n^{b}_{\beta}\nabla_{[a}\nabla_{b]}f_{1}$
$\displaystyle\stackrel{{\scriptstyle\Lambda}}{{=}}-\beta^{b}_{\alpha\beta}\bar{\nabla}_{b}\bar{f}\,.$

Indeed, unless $\bar{f}$ is constant or $\beta=0$, the submanifold extension
problem cannot be solved beyond first order. The case where $\bar{f}$ is
constant is uninteresting, as the solution is merely that $f=\bar{f}$. So
going forward, we assume that $\beta=0$ to proceed—that is, that
$\Lambda\hookrightarrow(M,g)$ has vanishing normal curvature and we choose a
parallelization of $N\Lambda$ such that $\beta=0$. Then, from the above
considerations, we have that there exists $f_{2}$ such that

$\nabla_{n_{\alpha}}f_{2}=F_{\alpha\beta\gamma}s_{\beta}s_{\gamma}\,.$

We wish to adjust $s$ such that $F$ vanishes along $\Lambda$, as before. So,
we write $f_{3}=f_{2}+A_{\alpha\beta\gamma}s_{\alpha}s_{\beta}s_{\gamma}$.
Indeed, by purely representation theory considerations, we have that
$F_{\alpha\beta\gamma}\in
C^{\infty}(M,\raisebox{3.0pt}{\scalebox{0.2}{\ydiagram{2,1}}}\;\oplus\;\raisebox{2.0pt}{\scalebox{0.2}{\ydiagram{3}}})$,
whereas $A_{\alpha\beta\gamma}\in
C^{\infty}(M,\raisebox{1.5pt}{\scalebox{0.2}{\ydiagram{3}}})\,$. We now
attempt to compute this obstruction as we did for the obstruction at first
order.

To do so, a straightforward calculation shows that

$\displaystyle F_{\alpha\beta\gamma}$
$\displaystyle\stackrel{{\scriptstyle\Lambda}}{{=}}\tfrac{1}{2}\nabla_{n_{\beta}}\nabla_{n_{\gamma}}\nabla_{n_{\alpha}}f_{2}$
$\displaystyle\stackrel{{\scriptstyle\Lambda}}{{=}}\tfrac{1}{2}n^{b}_{\beta}n^{c}_{\gamma}(\nabla_{b}\nabla_{c}n^{a}_{\alpha})\nabla_{a}f_{2}+\tfrac{1}{2}n^{b}_{\beta}n^{c}_{\gamma}n^{a}_{\alpha}\nabla_{b}\nabla_{c}\nabla_{a}f_{2}$
$\displaystyle\stackrel{{\scriptstyle\Lambda}}{{=}}\tfrac{1}{2}n^{b}_{\beta}n^{c}_{\gamma}(\nabla_{b}\nabla_{c}n^{a}_{\alpha})\bar{\nabla}_{a}\bar{f}+\tfrac{1}{2}n^{b}_{\beta}n^{c}_{\gamma}n^{a}_{\alpha}\nabla_{b}\nabla_{c}\nabla_{a}f_{2}$
$\displaystyle\stackrel{{\scriptstyle\Lambda}}{{=}}\tfrac{1}{2}n^{b}_{\beta}n^{c}_{\gamma}(\nabla^{\top\,a}\nabla_{b}n_{c\alpha})\bar{\nabla}_{a}\bar{f}+\tfrac{1}{2}R_{\gamma\alpha\beta}{}^{a}\bar{\nabla}_{a}\bar{f}+\tfrac{1}{2}n^{b}_{\beta}n^{c}_{\gamma}n^{a}_{\alpha}\nabla_{b}\nabla_{c}\nabla_{a}f_{2}$
$\displaystyle\stackrel{{\scriptstyle\Lambda}}{{=}}\tfrac{1}{2}R_{\gamma\alpha\beta}{}^{a}\bar{\nabla}_{a}\bar{f}+\tfrac{1}{2}n^{b}_{\beta}n^{c}_{\gamma}n^{a}_{\alpha}\nabla_{b}\nabla_{c}\nabla_{a}f_{2}\,,$

where the third identity follows from the known behavior of the normal
derivative of $f_{2}$, and the last identity follows because $\beta=0$. Of
interest is the component of $F$ that occupies the  2,1 representation—the
totally symmetric component is removeable via a judicious choice of $A$.

$\displaystyle
P_{\scalebox{0.2}{\ydiagram{2,1}}}\,F_{\alpha\beta\gamma}\stackrel{{\scriptstyle\Lambda}}{{=}}$
$\displaystyle\tfrac{1}{3}(F_{\alpha\beta\gamma}+F_{\beta\alpha\gamma}-F_{\gamma\beta\alpha}-F_{\gamma\alpha\beta})$
$\displaystyle\stackrel{{\scriptstyle\Lambda}}{{=}}$
$\displaystyle(P_{\scalebox{0.2}{\ydiagram{2,1}}}\,R_{\gamma\alpha\beta}{}^{a})\bar{\nabla}_{a}\bar{f}$
$\displaystyle+\tfrac{1}{6}\Big{(}n^{b}_{\beta}n^{c}_{\gamma}n^{a}_{\alpha}\nabla_{b}\nabla_{c}\nabla_{a}f_{2}+n^{b}_{\beta}n^{c}_{\gamma}n^{a}_{\alpha}\nabla_{a}\nabla_{c}\nabla_{b}f_{2}-n^{b}_{\beta}n^{c}_{\gamma}n^{a}_{\alpha}\nabla_{b}\nabla_{a}\nabla_{c}f_{2}-n^{b}_{\beta}n^{c}_{\gamma}n^{a}_{\alpha}\nabla_{a}\nabla_{b}\nabla_{c}f_{2}\Big{)}$
$\displaystyle\stackrel{{\scriptstyle\Lambda}}{{=}}$
$\displaystyle(P_{\scalebox{0.2}{\ydiagram{2,1}}}\,R_{\gamma\alpha\beta}{}^{a})\bar{\nabla}_{a}\bar{f}\,.$

Thus, we see that while not a necessary condition, a sufficient condition to
proceed to higher orders is to demand that $(M^{d},g)$ is flat. In fact, this
assumption allows us to solve the problem entirely:

######  Theorem 9.10.

Suppose $\Lambda^{d-k}\hookrightarrow(M^{d},g)$ is parallelizable, let
$s_{\alpha}$ be a canonical defining map, and let $\bar{f}\in
C^{\infty}\Lambda$. Then, there exists $f\in C^{\infty}\Lambda$ such that
$f|_{\Lambda}=\bar{f}$ and

$\nabla_{n_{\alpha}}f=\mathcal{O}(s)\,.$

Further, if the embedding has vanishing normal curvature and the embedding is
parallelized by the rotation minimizing frame, then we may find $f\in
C^{\infty}M$ satisfying

$\nabla_{n_{\alpha}}f=\mathcal{O}(s^{2})\,.$

Finally, if the embedding has vanishing normal curvature and $(M^{d},g)$ is
flat and the embedding is paralellelized by the rotation minimizing frame,
then there exists a unique $f\in C^{\infty}M$ satisfying

$\nabla_{n_{\alpha}}f=0\,.$

###### Proof.

The first two statements follow by the above considerations. Now suppose that
$\mathcal{R}=0=R$. We prove by induction. Suppose that there exists $f\in
C^{\infty}M$ such that $f|_{\Lambda}=\bar{f}$ and

$\nabla_{n_{\alpha}}f=F_{\alpha\beta_{1}\cdots\beta_{m-1}}s_{\beta_{1}}\cdots
s_{\beta_{m-1}}\,.$

First, we will show that $F$ is totally symmetric. By differentiating $m$
times, we find that

$\tfrac{1}{(m-1)!}F_{\alpha\beta_{1}\cdots\beta_{m-1}}=\nabla_{n_{\beta_{1}}}\cdots\nabla_{n_{\beta_{m-1}}}\nabla_{n_{\alpha}}f\,.$

From Lemma 4.2, it follows that up to $m-1$ normal derivatives on
$n^{a}_{\alpha}$ vanish. So,

$\tfrac{1}{(m-1)!}F_{\alpha\beta_{1}\cdots\beta_{m-1}}=n^{a}_{\alpha}n^{b_{1}}_{\beta_{1}}\cdots
n^{b_{m-1}}_{\beta_{m-1}}\nabla_{b_{1}}\cdots\nabla_{b_{m-1}}\nabla_{a}f\,.$

By hypothesis, covariant derivatives commute, and so $F$ is totally symmetric.

Now define $\tilde{f}=f+A_{\gamma_{1}\cdots\gamma_{m}}s_{\gamma_{1}}\cdots
s_{\gamma_{m}}$ for arbitrary $A$. Then,

$\displaystyle\nabla_{n_{\gamma_{1}}}\cdots\nabla_{n_{\gamma_{m}}}\tilde{f}$
$\displaystyle\stackrel{{\scriptstyle\Lambda}}{{=}}\nabla_{n_{\gamma_{1}}}\cdots\nabla_{n_{\gamma_{m}}}(f+A_{\alpha_{1}\cdots\alpha_{m}}s_{\alpha_{1}}\cdots
s_{\alpha_{m}})$
$\displaystyle\stackrel{{\scriptstyle\Lambda}}{{=}}(m-1)!F_{\gamma_{m}(\gamma_{1}\cdots\gamma_{m-1})}+m!A_{\gamma_{1}\cdots\gamma_{m}}\,.$

Because $F$ is totally symmetric, there exists a judicious choice of $A$ such
that we can totally eliminate $F$, and so we have that
$\nabla_{n_{\alpha}}\tilde{f}=\mathcal{O}(s^{m})$. This completes the
induction.

Now observe that there is a unique extension that sets the symmetric normal
derivatives (to a certain order) to zero, as given by Equation (9.2). As the
extension constructed here has all normal derivatives vanishing (up to a
certain order) it thus follows that it is indeed unique. ∎

We have thus determined sufficient conditions to solve Problem 9.9.

###  9.3. The Conformal Extension Problem

Considering the success of the Riemannian symmetric extension problem, we
consider the conformal equivalent:

######  Problem 9.11.

Let $\Lambda\hookrightarrow(M,\bm{c})$ be a parallelized conformal submanifold
embedding with an associated defining density $\sigma_{\alpha}$, let
$\bar{f}\in\Gamma(\mathcal{E}\Lambda[w])$, and let $m\in\mathbb{Z}_{\geqslant
2}$. Find $f\in\Gamma(\mathcal{E}M[w])$ satisfying $f|_{\Lambda}=\bar{f}$ and

$N_{\alpha}\cdot Df\stackrel{{\scriptstyle\Lambda}}{{=}}0\,,\qquad
N^{A_{1}A_{2}}_{(\alpha_{1}\alpha_{2})}D_{A_{1}A_{2}}f\stackrel{{\scriptstyle\Lambda}}{{=}}0\,,\qquad\ldots\,,\qquad
N^{A_{1}\cdots A_{m+1}}_{(\alpha_{1}\cdots\alpha_{m+1}}D_{A_{1}\cdots
A_{m+1})}f\stackrel{{\scriptstyle\Lambda}}{{=}}0.$

We provide the following ansatz to second order:

$\displaystyle\tilde{f}:=$ $\displaystyle
f-\sigma_{\beta_{1}}N^{B_{1}}_{\beta_{1}}\hat{D}_{B_{1}}f+\tfrac{1}{2}\sigma_{\beta_{1}}\sigma_{\beta_{2}}N^{B_{1}}_{(\beta_{1}}N^{B_{2}}_{\beta_{2})_{\circ}}\hat{D}_{B_{1}}\hat{D}_{B_{2}}f$
$\displaystyle+\tfrac{d-2k+2w-2}{2k(d-k+2w-2)}\sigma_{\beta_{1}}\sigma_{\beta_{1}}N^{B_{1}}_{\beta_{2}}N^{B_{2}}_{\beta_{2}}\hat{D}_{B_{1}}\hat{D}_{B_{2}}f+\tfrac{w}{d-2}\sigma_{\beta_{1}}\sigma_{\beta_{2}}(K_{\beta_{1}\beta_{2}}-F^{(2)}_{\beta_{1}\beta_{2}\gamma\gamma})f$
$\displaystyle+\mathcal{O}(\sigma^{3})\,,$

where $N^{B_{1}}_{(\beta_{1}}N^{B_{2}}_{\beta_{2})_{\circ}}$ satisfies
$\delta_{\beta_{1}\beta_{2}}N^{B_{1}}_{(\beta_{1}}N^{B_{2}}_{\beta_{2})_{\circ}}\stackrel{{\scriptstyle\Lambda}}{{=}}0$.
Formally, we are allowing ourselves to interchange between $D$ and $\hat{D}$,
noting that this will exclude some weights at the end of the construction.

By direct computation, one can check that indeed,

$N\cdot
D_{\alpha}\tilde{f}\stackrel{{\scriptstyle\Lambda}}{{=}}0\stackrel{{\scriptstyle\Lambda}}{{=}}N^{A_{1}}_{(\alpha_{1}}N^{A_{2}}_{\alpha_{2})}\hat{D}_{A_{1}}\hat{D}_{A_{2}}\tilde{f}\,.$

However, as the Thomas-$D$ operator is not a derivation, it becomes
increasingly challenging to construct $\tilde{f}$ so that more symmetric
normal Thomas-$D$s vanish on $\tilde{f}$. For brevity, we will halt the
solution here, observing that we can find a canonical extension unique to
second order in $f$ that solves Problem 9.11 to second order. Observe that
this extension is only well-defined when $w\neq
1-\tfrac{d-k}{2},1-\tfrac{d}{2}$.

For those sporadic weights, we must be more careful. When $w=1-\tfrac{d}{2}$,
we have trivially that $N_{\alpha}\cdot
Df\stackrel{{\scriptstyle\Lambda}}{{=}}0$, but the condition is vacuous and
hence we lose uniqueness—so we are halted here. However, when
$w=1-\tfrac{d-k}{2}$, we may instead omit the offending term from our ansatz.
In doing so, the ansatz no longer solves the problem to second order, but
instead solves the following system:

$N\cdot D_{\alpha}\tilde{f}\stackrel{{\scriptstyle\Lambda}}{{=}}0\,,\qquad
N^{A_{1}A_{2}}_{(\alpha_{1}\alpha_{2})_{\circ}}D_{A_{1}A_{2}}\tilde{f}\stackrel{{\scriptstyle\Lambda}}{{=}}0\,.$

Notably, we are obstructed from finding a solution that solves the full
problem and instead can only solve the trace-free equivalent. This observation
is consistent with the existence of the extrinsically-coupled conformal
submanifold Laplacian operator described Theorem 8.1. In fact, a slight
modification of the operator $P_{2}$ yields the problematic operator in the
ansatz. To see this, we first perform a useful computation:

$\displaystyle N_{\gamma}\cdot\hat{D}N^{A}_{\beta}$
$\displaystyle=N^{B}_{\gamma}\hat{D}^{A}N_{B\beta}$
$\displaystyle=N_{B(\gamma}\hat{D}^{A}N^{B}_{\beta)}+N_{B[\gamma}\hat{D}^{A}N^{B}_{\beta]}$
$\displaystyle=\tfrac{1}{2}\hat{D}^{A}G_{\gamma\beta}+\tfrac{1}{d-2}X^{A}K_{(\gamma\beta)}+B^{A}_{\gamma\beta}$
$\displaystyle=\tfrac{1}{2}\hat{D}^{A}(\sigma_{\rho_{1}}\sigma_{\rho_{2}}F^{(2)}_{\gamma\beta\rho_{1}\rho_{2}})+\tfrac{1}{d-2}X^{A}K_{(\gamma\beta)}+B^{A}_{\gamma\beta}$
$\displaystyle=\sigma_{(\rho_{1}}N^{A}_{\rho_{2})}F^{(2)}_{\gamma\beta\rho_{1}\rho_{2}}-\tfrac{2}{d-2}X^{A}\sigma_{(\rho_{1}}N_{\rho_{2})}\cdot\hat{D}F^{(2)}_{\gamma\beta\rho_{1}\rho_{2}}-\tfrac{1}{d-2}X^{A}\bm{G}_{\rho_{1}\rho_{2}}F^{(2)}_{\gamma\beta\rho_{1}\rho_{2}}$
$\displaystyle\phantom{=}+\tfrac{1}{d-2}X^{A}K_{(\gamma\beta)}+B^{A}_{\gamma\beta}+\mathcal{O}(\sigma^{2})\,.$

Consequently, we may write the $P_{2}$ in terms of the operator
$P_{2}^{\top}:=N^{B_{1}}_{\beta_{1}}N^{B_{2}}_{\beta_{2}}\hat{D}_{B_{1}}\hat{D}_{B_{2}}$
via

$\displaystyle P_{2}\stackrel{{\scriptstyle\Lambda}}{{=}}$ $\displaystyle
kN_{\alpha}\cdot\hat{D}N_{\alpha}\cdot\hat{D}$
$\displaystyle\stackrel{{\scriptstyle\Lambda}}{{=}}$ $\displaystyle
kP_{2}^{\top}+k(N_{\alpha}\cdot\hat{D}N^{B}_{\alpha})\hat{D}_{B}$
$\displaystyle\stackrel{{\scriptstyle\Lambda}}{{=}}$ $\displaystyle
kP_{2}^{\top}+\tfrac{k(k-d+2)}{2(d-2)}(K_{\alpha\alpha}-F^{(2)}_{\alpha\alpha\beta\beta})\,.$

Notably, as $P_{2}$ is a tangential operator, so is $P_{2}^{\top}$. So we find
that, when $\bar{f}\in\Gamma(\mathcal{E}\Lambda[\tfrac{2+k-d}{2}])$ satisfies
$P_{2}^{\top}\bar{f}\stackrel{{\scriptstyle\Lambda}}{{=}}0$, the ansatz
without the offending term solves the whole extension problem to order
two—otherwise, this obstruction genuinely prevents a full solution.

We may now summarize the results of this subsection in the following
proposition:

######  Proposition 9.12.

Let $\Lambda^{d-k}\hookrightarrow(M^{d},\bm{c})$ be a parallelized conformal
submanifold embedding with an associated defining density $\sigma_{\alpha}$.
Then, for any $\bar{f}\in\Gamma(\mathcal{E}\Lambda[w])$ with $w\neq
1-(d-k)/2,1-d/2$, there exists a unique $f\in\Gamma(\mathcal{E}M[w])$ modulo
terms of order $\sigma^{3}$ such that

$N\cdot D_{\alpha}f\stackrel{{\scriptstyle\Lambda}}{{=}}0\,,\qquad
N^{A_{1}A_{2}}_{(\alpha_{1}\alpha_{2})}D_{A_{1}A_{2}}f\stackrel{{\scriptstyle\Lambda}}{{=}}0\,.$

Furthermore, if $P_{2}^{\top}\bar{f}\stackrel{{\scriptstyle\Lambda}}{{=}}0$,
there exists a unique solution (modulo terms of order $\sigma^{3}$) even when
$w=1-(d-k)/2$.

## References

  * [1] L. Andersson, P. T. Chruściel, and H. Friedrich, On the regularity of solutions to the Yamabe equation and the existence of smooth hyperboloidal initial data for Einstein’s field equations, Comm. Math. Phys., 149 (1992), pp. 587–612.
  * [2] P. Aviles and R. C. McOwen, Complete conformal metrics with negative scalar curvature in compact Riemannian manifolds, Duke Math. J., 56 (1988), pp. 395–398.
  * [3] T. N. Bailey, M. G. Eastwood, and A. R. Gover, Thomas’s structure bundle for conformal, projective and related structures, Rocky Mountain J. Math., 24 (1994), pp. 1191–1217.
  * [4] S. Blitz, A. Gover, and A. Waldron, Conformal fundamental forms and the asymptotically poincar$\backslash$’e–einstein condition, Indiana Univ. Math. J., 72 (2023), pp. 2215–2283.
  * [5] A. Cap and A. Gover, Tractor bundles for irreducible parabolic geometries, global analysis and harmonic analysis (marseille-luminy, 1999), 129-154, Smin. Congr, 4.
  * [6] A. Čap and A. R. Gover, Standard tractors and the conformal ambient metric construction, Annals of Global Analysis and Geometry, 24 (2003), pp. 231–259.
  * [7] É. Cartan, Les espaces à connexion conforme, Ann. Soc. pol. Math., 2 (1923), pp. 171–221.
  * [8] S. N. Curry, A. R. Gover, and D. Snell, Conformal submanifolds, distinguished submanifolds, and integrability, 2023.
  * [9] A. Fialkow, Conformal differential geometry of a subspace, Trans. Amer. Math. Soc., 56 (1944), pp. 309–433.
  * [10] M. Glaros, A. R. Gover, M. Halbasch, and A. Waldron, Variational calculus for hypersurface functionals: singular Yamabe problem Willmore energies, J. Geom. Phys., 138 (2019), pp. 168–193.
  * [11] A. R. Gover, Almost Einstein and Poincaré-Einstein manifolds in Riemannian signature, J. Geom. Phys., 60 (2010), pp. 182–204.
  * [12] A. R. Gover, E. Latini, and A. Waldron, Poincaré-Einstein holography for forms via conformal geometry in the bulk, Mem. Amer. Math. Soc., 235 (2015), pp. vi+95.
  * [13] A. R. Gover and L. J. Peterson, Conformally invariant powers of the Laplacian, $Q$-curvature, and tractor calculus, Comm. Math. Phys., 235 (2003), pp. 339–378.
  * [14] A. R. Gover and A. Waldron, The $\mathfrak{so}(d+2,2)$ minimal representation and ambient tractors: the conformal geometry of momentum space, Adv. Theor. Math. Phys., 13 (2009), pp. 1875–1894.
  * [15] , Boundary calculus for conformally compact manifolds, Indiana Univ. Math. J., 63 (2014), pp. 119–163.
  * [16] , Submanifold conformal invariants and a boundary Yamabe problem, in Extended abstracts Fall 2013—geometrical analysis, type theory, homotopy theory and univalent foundations, vol. 3 of Trends Math. Res. Perspect. CRM Barc., Birkhäuser/Springer, Cham, 2015, pp. 21–26.
  * [17] , A calculus for conformal hypersurfaces and new higher Willmore energy functionals, Adv. Geom., 20 (2020), pp. 29–60.
  * [18] , Conformal hypersurface geometry via a boundary Loewner–Nirenberg–Yamabe problem, Commun. Anal. Geom., 29 (2021), pp. 779–836.
  * [19] C. R. Graham and M. Zworski, Scattering matrix in conformal geometry, Invent. Math., 152 (2003), pp. 89–118.
  * [20] V. N. Gribov, Quantization of non-abelian gauge theories, Nuclear Physics B, 139 (1978), pp. 1–19.
  * [21] P. Hájíček, Exact models of charged black holes: I. geometry of totally geodesic null hypersurface, Communications in Mathematical Physics, 34 (1973), pp. 37–52.
  * [22] P. Hájíček, Stationary electrovacuum spacetimes with bifurcate horizons, Journal of Mathematical Physics, 16 (1975), pp. 518–522.
  * [23] M. Henningson and K. Skenderis, The holographic Weyl anomaly, J. High Energy Phys., (1998), pp. Paper 23, 12.
  * [24] C. Loewner and L. Nirenberg, Partial differential equations invariant under conformal or projective transformations, in Contributions to analysis (a collection of papers dedicated to Lipman Bers), 1974, pp. 245–272.
  * [25] J. Maldacena, The large $N$ limit of superconformal field theories and supergravity, Adv. Theor. Math. Phys., 2 (1998), pp. 231–252.
  * [26] R. Mazzeo, Regularity for the singular Yamabe problem, Indiana Univ. Math. J., 40 (1991), pp. 1277–1299.
  * [27] A. Mondino and H. T. Nguyen, Global conformal invariants of submanifolds, in Annales de l’Institut Fourier, vol. 68, 2018, pp. 2663–2695.
  * [28] C. Robin Graham and N. Reichert, Higher-dimensional Willmore energies via minimal submanifold asymptotics, Asian J. Math., 24 (2020), pp. 571–610.
  * [29] J. Šilhan and V. Žádník, Conformal theory of curves with tractors, Journal of Mathematical Analysis and Applications, 473 (2019), pp. 112–140.
  * [30] M. Spivak, A Comprehensive Introduction to Differential Geometry, Publish or Perish, Inc., 1999.
  * [31] T. Y. Thomas, On conformal geometry, Proceedings of the National Academy of Sciences, 12 (1926), pp. 352–359.
  * [32] K. K. Uhlenbeck, Connections with lp bounds on curvature, Communications in Mathematical Physics, 83 (1982), pp. 31–42.
  * [33] P. van Baal, More (thoughts on) gribov copies, Nuclear Physics B, 369 (1992), pp. 259–275.
  * [34] W. Wang, B. Jüttler, D. Zheng, and Y. Liu, Computation of rotation minimizing frames, ACM Transactions on Graphics (TOG), 27 (2008), pp. 1–18.
  * [35] T. J. Willmore, Note on embedded surfaces, An. Sti. Univ.“Al. I. Cuza” Iasi Sect. I a Mat.(NS) B, 11 (1965), p. 20.
  * [36] P. Yang, S.-Y. Chang, and J. Qing, Renormalized volumes for conformally compact Einstein manifolds, Sovrem. Mat. Fundam. Napravl., 17 (2006), pp. 129–142.


# The Paradox of Function Header Comments††thanks: This research was supported
by the ISRAEL SCIENCE FOUNDATION (grant no. 832/18).

Arthur Oxenhorn Almog Mor Uri Stern Dror G. Feitelson
Department of Computer Science
The Hebrew University, Jerusalem, Israel

###### Abstract

Perhaps the most widely used form of code documentation is function header
comments. We performed a large-scale survey of 367 developers to catalog their
expectations from such documentation and to chronicle actual practice.
Paradoxically, we found that developers appreciate the value of header
comments and estimate that they are worth the investment in time, but
nevertheless they tend not to write such documentation in their own code.
Reasons for not writing header comments vary from the belief that code should
be self-documenting to concern that documentation will not be kept up-to-date.

A possible outcome of this situation is that developers may evade requirements
to write documentation by using templates to generate worthless comments that
do not provide any real information. We define a simple metric for
information-less documentation based on its similarity to the function
signature. Applying this to 21,140 files in GitHub Python projects shows that
most functions are undocumented, but when header comments _are_ written they
typically do contain additional information beyond the function signature.
Keywords: documentation, function headers, header comments

##  1 Introduction

When faced with the task of understanding a computer program, the two chief
sources of information are the program’s code itself and the documentation of
this code. The documentation in the code can be divided into two main parts:
class and function header comments, and inline comments [14]. Function header
comments in particular are used to describe the algorithm implemented by the
function or to document its interface, in both cases with the goal to
eliminate or at least reduce the need to read and comprehend the code itself.
Thus they support a top-down approach to code comprehension [32, 3, 24, 22].
Inline comments complement this by explaining elements of the code that may
not be obvious on their own right. This is especially useful when trying to
comprehend the actual code, for example in the context of maintaining it.

The potential importance of comments is generally recognized, and writing
header comments is often required in coding guidelines. On the other hand,
many have also expressed concern regarding the quality and relevance of
comments [28, 29, 12, 30]. Berry et al. note the problem that documentation is
usually beneficial for its reader, not its writer, thereby reducing the
incentive to write good comments [4]. A related issue is the need to update
comments as code evolves [17]; a possible solution is to only produce the
comments at the code review stage, when the code is being finalized [12].
Other studies claim that documentation just does not have a significant effect
on code comprehension [6].

Functions are the most-often commented code elements [11]. The practice of
function documentation depends on the programming language used. In C and C++
a distinction is made between comments in header files, which document the
interface, and comments in code files, which document the implementation. In
Java it is common to format header comments for JavaDoc, which automatically
generates external documentation of APIs [15]. Python and other languages
support docstrings, that remain available also during execution. These
practices are intended to support developers who need to use functions written
by others.

But in the last 20 years or so the notion that code should be self-documenting
has gained traction. This approach to programming emphasizes the need to use
clear variable and function names, with the aim of not having to add any
comments at all. Steve McConnell, in a whole chapter devoted to writing
functions in Code Complete, does not even mention header comments [21]. He
does mention them elsewhere as a first step in writing pseudocode leading to
an implementation. As for using documentation in general, McConnell strongly
opposes predefined enforced header comment guidelines, preferring that
documentation reflect the complexity of the function. Parameters should only
be described if one is using an automatic documentation-generation facility
such as JavaDoc. Robert Martin, in Clean Code — which also has a whole chapter
on functions — is more terse. His subsection on header comments contains only
two sentences: “Short functions don’t need much description. A well-chosen
name for a small function that does one thing is usually better than a comment
header.”

Given such widely diverging views on the utility and need of header comments,
we turn to see what developers do in practice, and how they perceive header
comments in their everyday work. What should function header comments, and API
documentation in general, contain? What do developers need and want? And do
they in fact act according to what they say they want?

The contributions of this paper are the following:

  1. 1.

We conduct a large-scale survey of developers, and collect information on
their practices concerning the use and production of function header
documentation, what they find most useful in such documentation, and what is
most often missing;

  2. 2.

We uncover paradoxical behavior, where developers tend to use and value
function header comments and think they are worth the investment, but
nevertheless tend not to write them;

  3. 3.

We refine the definition of a simple metric for determining whether function
header documentation contains additional information beyond the function
signature;

  4. 4.

We collect data about the use of function header comments in Python projects,
showing that most functions are undocumented, but in most documented functions
the documentation does contain novel information beyond the function
signature.

##  2 Related Work

Documentation is widely accepted as an element of programming, and there has
been a significant amount of work on how to write comments and on their
effect. Steidl at al. present a classification of comment types and suggest
simple metrics for their quality [28]. Aggarwal et al. base their model of
software maintainability on three aspects of documentation: the percentage of
comment lines, the simplicity of the comments text, and the correlation
between documentation vocabulary and the code vocabulary [1]. Other research
indicates that documentation complements the information contained in variable
names [5], and that it can compensate for low code quality [16]. Even
redundant documentation (for example explicitly stating what design pattern is
being used) may still help somewhat [25]. Documentation’s utility may also
depend on experience: novices appear to focus on comments more than
experienced programmers [9].

Function header comments used to document APIs (Application Programming
Interfaces) have received special attention. Liskov and Guttag suggest that
functions need a specification comment containing a pair of assertions: the
function’s precondition and its postcondition [19]. This is part of the
abstraction (and specifically procedural abstraction) that also supports
formal verification and testing, and is thought to be sufficiently informative
to allow others to use the function without looking at its body. Meyer makes a
similar suggestion, in the form of function contracts [23]. In addition to
documentation, the function name itself if considered important for
understanding what a function does. Alsuhaibani el al. conducted a large
survey of developers, and found that there is large agreement on the basic
principles of function naming [2].

Other research has looked at how developers use API documentation. This is
usually based on surveys of developers, similar in spirit to our work [12,
22]. Watson et al. complement surveys with collecting data from actual
practice in open source projects [31].

Research that uncovered problems in API documentation can be especially
revealing. Robillard found that problematic or missing documentation is only
one of the problems in learning to use an API [27]. Other problems include the
API itself (e.g. if it is badly designed) and lack of background knowledge.
Moreover, deficiencies in API documentation may cause the API to be abandoned
and another to be used in its place [29]. Watson et al. add that having
required elements is not enough for effective documentation: issues like the
writing style, visual design, and ease of finding the documentation are also
important [31]. Curtis et al. found that using a restricted language forces
consistency that can be helpful [10].

Finally, in a survey of research on documentation, Rai et al. note that a
favorite topic is the generation of summaries of functions [26]. For example,
Huang et al. describe a method that combines information retrieval with neural
networks for the purpose of generating a general description of a function
[13]. More recently large language models are also being applied to this
problem.

##  3 Research Questions

The general goal of our research was to learn whether function header
documentation indeed helps developers in understanding functions’ usage,
thereby saving the effort to read and understand the actual code. If it turns
out that this is _not_ the case, then the effort invested in writing comments
has been wasted, and doing so can be avoided.

To gain insights into this issue, we formulated the following concrete
research questions:

  1. 1.

To what degree is function header documentation used in practice? What
fraction of functions have such documentation? What fraction of developers
rely on such documentation, and what fraction actually invest in writing
header comments in their code? These questions will show whether this topic is
important at all, and specifically how developers see it.

  2. 2.

Which parts of function header documentation (parameters, return value,
examples) are the most useful? How often are they actually included in header
comments? This may shed light on when developers can make do with the
documentation, and when they also need to read the code.

  3. 3.

What necessary information is most often missing from function header
documentation, thereby making it ineffective? Answering this question can
provide guidance concerning how header comments can be improved.

  4. 4.

In general, does function header documentation add meaningful information
beyond the function’s signature? Or is it redundant? This will tell us whether
function and parameter names are meaningful enough to eliminate the need for
header comments.

To answer these questions we employed two methodologies: a survey and
repository mining. The survey was answered by 367 developers from around the
world. It had two main parts. In one we asked about perceptions regarding
header comments: how useful they were thought to be, and which parts (e.g. the
explanation of parameters, return value, or internal structure) were more
important than others. In the other we asked about actual practice: whether
functions in the project they work on have header comments, whether they
themselves write such comments, and why.

In the repository mining we scanned the code in 21,140 files from 68 top-
ranked python projects hosted on GitHub. We extracted the doc strings of the
functions in these files, and compared them with the function signatures. This
provides a simple measure of whether the documentation contains any additional
information beyond the function signature itself.

##  4 Survey on Perception and Use of Header Comments

We conducted a survey among developers from different backgrounds and
locations, to see what they think of header comments and how they use them.

###  4.1 Survey Design

The survey was composed of the following sections:

  1. 1.

Questions on how much developers read and rely on function header
documentation. This part included questions on whether they read this
documentation first; if so, what do they most focus upon (explanation of the
parameters, the function’s inner methods, its return value, or usage
examples), and does reading the documentation suffice to understand the
function’s usage; if not, why not, and whether they return to read it at a
later stage.

  2. 2.

Questions on how useful developers find the information in header comments to
be (even if they do not actually read it for various reasons), and which parts
of it are the most useful ones. An additional question concerned what
information is usually lacking from such documentation.

  3. 3.

Questions about how much effort developers spend in writing and updating
function header comments, and whether they feel it is worth the time this
consumes.

  4. 4.

Questions on the current practice of documenting code in their workplace. For
this we asked about the existence of company and team guidelines for
documenting code.

  5. 5.

Lastly, we asked some demographic questions: age, gender, experience in
programming, main programming language used, original programming education,
and main programming activity today.

The survey was mostly based on multiple choice questions, on a scale of 1–5,
where 1 means “not at all important” or “strongly disagree” and 5 means “very
important” or “strongly agree”. In addition we used open questions where
participants could expand on issues that they found missing in the multiple
choice questions.

###  4.2 Survey Execution

The survey was implemented on the Google Forms platform. Requests to
participate in the survey were distributed both locally and globally. Locally
the survey was posted to student WhatsApp groups and Facebook groups, and sent
directly to colleagues. Globally the invitation to participate was posted to a
few Reddit groups. Consent to participate was explicitly implied by continuing
from the introductory page to the survey questions. No identifying information
was collected, and participants were not compensated for taking the survey.

A total of 367 people responded to the survey. 89% were men, 5.4% were women,
and a similar fraction preferred not to identify or gave a different answer.
While this is highly skewed, it appears to be representative of the developer
community as reflected by the Stack Overflow developer
survey111https://survey.stackoverflow.co/2022#developer-profile-demographics.
Of the 265 who answered the question about where they are from, 85 were from
the United States, 41 from Israel, 28 from the United Kingdom, 19 from
Germany, and 8 each from the Netherlands and Australia. The rest came from 34
other countries. The ages of three quarters of the respondents were between 20
and 40, with 22% being in the range 30–35. Another quarter were above 40, with
8% even above 50.

Concerning programming experience, 51% had learned to program in a university
or college, and 31% studied independently. 10% learned at work, in a bootcamp,
or during military service. 88% reported that their main programming activity
is done at work. 8% said it was done in independent projects, and the rest
programmed in a research setting. Their years of experience were rather
skewed: 36% had 0–5 years of experience, and another 24% had 6-10 years. 13%
claimed 21 years of experience or more. The combination of programming at work
and the years of experience indicate that the vast majority of participants
are professional developers. The main programming languages used by
participants were Python, TypeScript, and JavaScript, with 24–27% naming them.
C# was named by 18%, Java by 13%, and ten additional languages by 3–12%.

###  4.3 Survey Results

####  4.3.1 Use and Utility of Function Header Comments

We started the survey with a general question about actual practice: does the
participant’s current project have documented functions? A bit more than a
quarter of the participants answered that no, functions are not documented. A
a bit less than half said that most functions do not have header comments but
some do, and a bit more than a quarter said that most do.

Does the codebase/project you currently work on have documented functions?
---

The next question was about their personal behavior, and specifically where do
they start from when they need to use a function they did not write. More than
half answered that they first read the header documentation (including its
signature). More than a third said they first read the code. Few said they
turn to external documentation or mentioned other options, such as tests.

When you need to use a function you didn’t write for the first time, what do
you read first in order to understand the function usage?
---

Based on these answers, we asked those who said they start with the header
comments whether this was enough. The majority agreed that this was indeed the
case, and that it is not necessary to also read the code.

Usually, one does not need to read the actual code to use the function, and can read only its header documentation to use it [scale: 1=strongly disagree to 5=strongly agree] |  $1$$2$$3$$4$$5$$0$$10$$20$$30$$40$Percents
---|---

Alternatively, those who said they do not start with the header documentation
were asked why. More than half chose the option that code gives better
understanding. Around 40% each selected criticisms of header documentation
(not good or not up to date — a concern that has also been noted in other
research [12, 18]) or that reading the code was simpler. Few entered their own
reasons — that header documentation was missing, or that external
documentation was better.

Why do you start from the code/external documentation and not the function
header documentation?
---
$0$$10$$20$$30$$40$$50$$60$Header docs often not up to dateReading code is
simplerHeader docs are not goodCode gives better understandingPercents

In addition, they were asked whether they later do read the header
documentation. The answers indicate that about a third sometimes do (answered
3), but half tend not to (1 or 2). Only a small minority tend to read header
documentation later (4 or 5).

How often do you go back to reading the function header documentation in later stages of understanding its usage? [scale: 1=never to 5=always] |  $1$$2$$3$$4$$5$$0$$10$$20$$30$$40$Percents
---|---

Finally, all the participants were asked about their perception of the
usefulness of function header documentation. The majority thought they were
useful.

How useful do you think functions’ header documentation is? [scale: 1=not at all to 5=very much] |  $1$$2$$3$$4$$5$$0$$10$$20$$30$$40$Percents
---|---

####  4.3.2 The Elements of Function Header Comments

Header comments usually include several parts. We specifically considered
four: descriptions of the parameters, of the return value, of the internal
structure, and usage examples. The justifications for choosing them are as
follows: Parameters and return value are universally considered the basic
requirement to define an API; Inner functions represent implementation
details; Examples are known to be desirable from past work.

All the participants were asked: In your opinion, how useful are the following
parts of function header documentation? The answers to these questions are
shown in orange in the following graphs, on a scale of 1=not useful to 5=very
useful.

Participants who had previously answered that they read header comments first
were also asked: When reading function header documentation, how much do you
focus on [these parts]? The answers are shown in blue, on a scale of 1=not at
all to 5=very much.

The results indicate that a strong correlation exists between the perception
of usefulness by all participants and the focus by those participants who
indeed read header documentation first. The output definition and return value
are valued most, closely followed by usage examples. Explanations of the
function parameters are also thought useful, but to a somewhat lesser degree.
The function’s internal methods, on the other hand, are not considered useful
or focused upon. This is as can be expected when the header comments are used
to learn how to use the function, as opposed to maintaining it.

Orange: How useful are, and blue: How much do you focus on: Explanations of the function’s parameters |  $1$$2$$3$$4$$5$$0$$10$$20$$30$$40$Percents
---|---
Orange: How useful are, and blue: How much do you focus on: Output definition and return value |  $1$$2$$3$$4$$5$$0$$10$$20$$30$$40$$50$Percents
Orange: How useful are, and blue: How much do you focus on: Explanation of the function’s inner methods |  $1$$2$$3$$4$$5$$0$$10$$20$$30$$40$Percents
Orange: How useful are, and blue: How much do you focus on: Examples of usage |  $1$$2$$3$$4$$5$$0$$10$$20$$30$$40$$50$Percents

Participants who said they read header documentation were then asked what
other parts of the documentation they look for beyond the four we asked about
explicitly. A bit more than a third answered this question. About 20% each (of
those who answered) mentioned a general description of the function and types.
Several respondents also mentioned other data items, such as exceptions, side
effects, and more.

Finally, all participants were asked a follow-up open question concerning
information that is often lacking from function header documentation. The most
commonly cited missing element by far was examples of usage, mentioned by 42%.
The next three issues, mentioned by 16% each, were exceptions, side-effects,
and being up to date.

What information is usually lacking in functions’ header documentation? (open
question)
---
$0$$10$$20$$30$$40$$50$PerformanceParameter descriptionsDescription of return
valuesTypesBeing up to dateSide effectsExceptionsExample/usagePercents

####  4.3.3 Writing Function Header Comments

The questions about writing header comments were preceded by a note that
participants who do not do so may not answer this part. Nevertheless, 350
participants (95%) did answer these questions.

The first two questions in this part of the survey exhibit somewhat
inconsistent behavior of the participants: most of them think that writing
function header documentation is worth the time it requires, but many often do
not actually write such documentation. Note that the question specifically
noted that we are referring to functions that might be used by other
developers in the future, not internal private functions.

Do you think writing function header documentation is worth the time it requires? [scale: 1=not at all to 5=very much] |  $1$$2$$3$$4$$5$$0$$10$$20$$30$$40$Percents
---|---
How often do you write documentation to your functions that other people might use in the future? [scale: 1=never to 5=always] |  $1$$2$$3$$4$$5$$0$$10$$20$$30$Percents

Expecting that this may be the case, we asked those who tend not to write
function header documentation (identified as those who answered 1 or 2) why
they behave this way. The most common answer given, by more than a third of
the participants, is that in fact they feel such documentation is unimportant
(we include here respondents who mentioned alternatives like good names,
especially for short simple functions, or external documentation). Around a
sixth each answered that it requires too much time, that self-explanatory code
is more important, and that it is not commonly done in their team. Of these,
the answer that self-explanatory code is more important was not suggested by
us, but written in under “other”. Additional answers given under “other”
include the code being for internal use only, the danger of the documentation
not being updated, and that it interrupts the workflow and is then forgotten.

Why do you avoid writing function header documentation?
---
$0$$10$$20$$30$$40$OtherTests explain the code better [other]The functions are
for internal use [other]Danger that it won’t be updated [other]It’s important
but uncommon in my teamSelf explanatory code more important [other]It’s
important but requires too much timeI feel it’s unimportantPercents

Those who answered 3–5 to the question of how often they document functions
were asked how much they elaborate on different elements in this documentation
(using a scale of 1=not at all to 5=a lot). The answers indicated that there
was some elaboration on parameters, and less on examples — in both cases much
less than reflecting the perceived importance of these elements as reported
above. There was a strong tendency not to elaborate on internal functions,
which we saw are indeed not perceived as important.

How much do you elaborate in explaining the function’s parameters in its header documentation? |  $1$$2$$3$$4$$5$$0$$10$$20$$30$$40$Percents
---|---
How much do you elaborate in explaining the function’s inner methods in its header documentation? |  $1$$2$$3$$4$$5$$0$$10$$20$$30$$40$$50$Percents
How much do you elaborate in explaining the function’s examples of usage in its header documentation? |  $1$$2$$3$$4$$5$$0$$10$$20$$30$Percents

Finally, we asked all participants how often they update the documentation
compared with updating the function’s code. The answers indicate that
developers tend not to update the documentation as much as may be desired,
justifying the reservations reported above concerning documentation that may
not be up to date. However, we note that Malik et al. found that the fraction
of comments that were not updated in 3 of the projects they studied were lower
than would be expected by our survey, ranging from 18% to 33%; in only one
project it was a high 62% [20]. Likewise, Chen et al., in a study on
identifying comments scope, estimated that only around 13% of the comments in
their sample were outdated [8]. This discrepancy might be explained by code
updates that do not require a change in the header comment, for example
because they just fix a bug.

How often do you update the function header documentation, compared to the updates in the function’s code? [scale: 1=never to 5=in every code update] |  $1$$2$$3$$4$$5$$0$$10$$20$$30$$40$Percents
---|---

####  4.3.4 Using Tools and Documentation Templates

A couple of questions concerned the use of auto-generated documentation and
its quality. The first showed that half the participants never use such tools.

How often do you use tools for automatic documentation generation (e.g. docstring generation tools built into IDEs)? [scale: 1=never to 5=very often] |  $1$$2$$3$$4$$5$$0$$10$$20$$30$$40$$50$Percents
---|---

The second question actually had two versions. All participants were asked:
How much do you think automatically generated documentation should be changed?
This is shown in orange in the graph, on a scale of 1=not at all (useful as it
is) to 5=a lot (useful only if edited). The second version was directed only
to participants who do use automatic generation, who were asked: How much do
you edit or add to the generated docstring? This is shown in blue, with a
scale of 1=I don’t edit anything to 5=I edit a lot. The result show a wide
spread of opinions, with a moderate correlation between thinking generated
documentation should be edited and actually doing it.

Orange: How much should auto-generated docstrings be changed? |
---|---
Blue: How much do you edit or add to them? |  $1$$2$$3$$4$$5$$0$$10$$20$$30$$40$Percents

####  4.3.5 Function Header Comments Guidelines

Finally, we asked participants whether they are required to document the
functions they write. Nearly two thirds of the respondents said no, and a
quarter said yes but that there were no explicit guidelines. Less than 8% said
they had explicit guidelines to document functions. A few participants added a
comment to the effect that they are required to document only complex
functions, or public/main functions. Two said that documentation is forbidden.

Are you required by your team’s/company’s guidelines to document the functions
you write?
---

A follow-up question for those who said they have documentation guidelines
asked what these guidelines included. The most common elements were a summary
or general explanation of the function (86%), and an explanation of its
parameters (56%). Only 20% were required to provide examples, which were
identified above as a part that is often missing.

If your group has guidelines, what do they require?
---
$0$$20$$40$$60$$80$$100$Explanation of function’s inner methodsExamples of
usageUsing an automatic template/docstringExplanation of parametersShort
summary/general explanationPercents

Alternatively, those who did not have documentation guidelines were asked why
not (this was an open question). The most common answer, given by 31%, was
that code should be self-documenting. 24% cited a startup culture, including
not having enough time or having a small team. Many others had opposing
opinions on the matter: 19% noted that they do not want documentation, while
14% were critical of the fact that documentation guidelines do not exist. Some
of these were downright disparaging of the company, using “they” to describe
managers who make such decisions without understanding their consequences.

What is the reason your team/company does not require writing function
documentation?
---
$0$$10$$20$$30$Documentation is hard to maintainCriticism on not requiring
documentationDon’t want documentationStartup cultureCode should be self-
documentingPercents

For example, one of the detailed comments we received was: “1. Concise and
explanatory code is more readable than documentation; 2. Documentation needs
to be maintained. When it’s not maintained it can be harmful: it gets out of
sync and the docs turn to be unreliable. When it’s unreliable people will
ignore it altogether, and the handful of functions that really need to be
elaborated can’t be documented anymore.” Another wrote: “Comments are a last
resort if you can’t make the code simple enough to understand on its own. By
making comments rarer you know that if there’s a comment it’s probably worth
reading.”

###  4.4 Discussion: The Paradox

The above results include many interesting observations and opinions about
function header documentation. But the most interesting and important in our
mind is the following paradox. On the one hand,

  * •

When using a function for the first time, 56% turn to header documentation

  * •

There is general agreement (answers of 4 or 5 on a scale of 1 to 5) that:

    * –

Header documentation is useful (59.7%)

    * –

One can read only the header documentation and avoid reading the code (57.6%)

    * –

Writing function header documentation is worth the time it requires (56.8%)

But on the other hand

  * •

In only 27% of the projects most functions have header documentation, and in
26% none have

  * •

Only 7.7% of projects have explicit guidelines requiring header documentation,
while 62.3% have no guidelines of any kind

  * •

Only 45.4% of developers often write header documentation (answers 4–5), while
33.4% often do not (answers 1–2) — _in functions that other people might use_

More specifically, the most significant disparity concerns examples. 72.8%
thought that usage examples are useful, and 61.7% said they focus on usage
examples when reading header documentation. At the same time 42% said that
usage examples are usually lacking from function header documentation, and
only 18.7% had guidelines that require usage examples. Likewise, 36.1%
elaborate on explaining usage examples when writing header documentation
(answers 4–5), but 44.1% do not (answers 1–2). These results mirror those of
Robillard from a survey of Microsoft employees, which also found examples to
be the number one requirement from helpful API documentation [27].

Luckily, this also points to what can be done to improve the situation. The
two recommendations that stand out are:

  1. 1.

Draft guidelines that require function header documentation to be written,
especially for public and complex functions.

  2. 2.

Require that function header comments include examples of usage. This can be
made easier using an example synthesizing approach such as that of Buse and
Weimer [7]. according to Meng et al., this should include both examples of
simple use cases and recipes for more special use cases [22].

##  5 Mining GitHub for Data on Useless Header Comments

One of the responses to the survey question of why do you not write header
comments was “Most documentation seems redundant given the naming and typing
of arguments/return values”. This identifies a major question hounding our
analysis of the perception of header comments: are they in fact needed at all?
maybe all the pertinent information is already available in the function
signature?

This also resonates with the practice of using documentation templates that
include descriptions of parameters with no added value. We’ve all seen
examples such as this one (used as an example of what to avoid in an Oracle
tutorial on using JavaDoc):

      /**
      * Sets the tool tip text.
      *
      * @param text  the text of the tool tip
      */
      public void setToolTipText(String text) {

Obviously, the comment just repeats words that make up the signature. We use
this as inspiration for how to identify meaningless comments. Given an
implementation of this definition, we apply it to the files of multiple
popular Python GitHub projects, and extract the distribution of
“meaninglessness”. This shows the prevalence of writing meaningless
documentation, and conversely — the fraction of header comments that in fact
contain additional information.

###  5.1 Defining “Meaningless” Header Comments

Header documentation is not the same as summarization. A key element in
documenting APIs is to document the interface itself (parameters and return
values). This is also what is required for contracts, and is implemented in
various tools. Our metric is aimed at this part of the documentation.

The metric for meaningless documentation is based on the idea that words that
appear in the function signature do not add information when they are repeated
in the header documentation. This is essentially similar to the “coherence
coefficient” suggested by Steidl et al. [28]. However, our procedure to
quantify it has several added features:

  1. 1.

For each function, we start with the full function signature (denoted $Sig$)
and with its header documentation (denoted $Doc$).

  2. 2.

We process the documentation string as follows:

    1. (a)

First we partition it into words. This is done in several steps. The first is
to replace every sequence of non-alphanumeric characters with a space. Note
that this already handles names that are written in snake_case style. We also
separate names written in camelCase into their constituent words based on
their internal capitalization. The result of this step is a list of individual
words in the documentation.

    2. (b)

From the list of words created in the previous step we extract the potentially
meaningful words. These are words that satisfy two conditions:

       * •

They are longer than a single character, and

       * •

They are not a stop word. The list of stop words we used is ‘the’, ‘an’, ‘of’,
‘at’, ‘by’, ‘in’, ‘it’, ‘on’, ‘to’, ‘that’, ‘had’, ‘for’, ‘was’, ‘were’. Note
that certain words that are commonly included in lists of stop words are _not_
included here, as they may be very meaningful in the specification of
functions. Examples are ‘and’, ‘or’, ‘is’.

    3. (c)

The list of extracted words is denoted $W_{Doc}$, and the number of these
words is $|W_{Doc}|$. Note that this is a bag and not a set: words may appear
in it more than once.

  3. 3.

We process the function signature as follows:

    1. (a)

First we partition it into words. This is done essentially in the same way as
was done with the documentation string.

    2. (b)

We create a set of all the words that appear in the signature, denoted
$W_{Sig}$. Note that this includes all of the following:

       * •

Words that appear in the function name

       * •

Words that appear in the function’s parameters

       * •

Words that appear in types of parameters and in the return type (if specified)

This is a set. There is no need to retain repetitions.

  4. 4.

For each word in the documentation, we check whether it appears in the
signature, and if so declare it to be meaningless. This is done in two steps:

    1. (a)

For each word $w\in W_{Doc}$ we check whether $w\in W_{Sig}$. This is
straightforward inclusion of the word.

    2. (b)

If the word $w$ is not found, we check the opposite direction: for each word
$v\in W_{Sig}$ we check whether $v\subset w$. This checks whether the
signature includes shortened versions of words in the documentation. For
example, ‘information’ in the docstring would be counted as meaningless if
‘info’ appears in the signature.

The list of words from the documentation identified as meaningless is denoted
$M$, and their number is $|M|$. This is a bag, with possible repetitions.

  5. 5.

Finally, we define the meaningless score of the function as $|M|/|W_{Doc}|$,
namely the fraction of potentially meaningful words in the documentation that
were found in the signature and are therefore actually meaningless. Thus, a
large score (close to 1) indicates a rather meaningless documentation, as the
information it provides was already given in the function’s signature.

Note that the above procedure defines “meaningless” based on the matching of
individual words, and does not rely on semantics. Thus it is actually a rather
crude and preliminary definition. We leave the task of designing more
sophisticated metrics for the meaningful data provided by documentation to
future work.

###  5.2 The GitHub Dataset

To check the actual prevalence of meaningless header documentation, 68 Python
repositories were analyzed. Repositories were chosen by popularity on GitHub,
based on the Github Ranking as reflected in the Top 100 Stars in Python
list222https://github.com/EvanLi/Github-Ranking/blob/master/Top100/Python.md.
This is a dynamic list and gets updated frequently; the lists that were used
are from December 2022 to January 2023.

Within each project we focused on the actual functional code and avoided test
code, as identified by “test” (including plural or capitalized) or “e2e”
appearing in the path. A total of 21,650 files were analyzed. 510 of them
(2.3%) failed to be parsed (some because of encoding errors, some because of
errors in the docstring_extractor library used in the script). The presented
results are based on the remaining 21,140 files.

For each file we count the total number of functions in the file and the
number of functions without any header documentation. In addition we extract
the docstrings from functions that do have one. This is done using the
function get_docstrings from the docstring_extractor Python
library333https://pypi.org/project/docstring-extractor/. In addition, we use
Python’s ast (abstract syntax tree) library to extract function parameters and
their types (if they exist). We then apply the procedure described above to
calculate the meaningless score of the docstring of each function, and collect
these results.

###  5.3 Results on Meaningless Header Comments

We first calculate the average fraction of functions with no documentation. To
avoid giving more weight to large files, we first find the fraction of such
functions in each file and then average over all the files from all the
projects. The resulting average fraction of functions with no documentation
was 0.596. This means that most functions are undocumented, as was also found
in the survey. The following results pertain to the other functions, which do
have docstrings.

Figure 1:  Distribution of meaningless score for all functions that have
docstrings.

Figure 1 shows the CDF (cumulative distribution function) of the meaningless
score of all the functions from all the projects. For every value of
meaningless score on the horizontal axis this shows the fraction of all
functions whose header documentation has a meaningless score up to this value.
The graph indicates that the central 80% of the distribution of functions have
a meaningless score in the range 0.15–0.45. In other words, for the vast
majority of functions more than half the words in the header documentation are
novel and do not appear in the function signature. This is similar to the
result obtained by Steidl et al., who found (in a sample of 5 projects) that
1–9% of the header comments were “trivial”, which they defined as having at
least half of their words appear in the function signature.

Figure 2:  Distribution of meaningless score for the functions in different
projects.

To verify that these results are indeed representative we plot the CDF of
meaningless scores for each studied project separately. All these graphs are
shown together in Figure 2. As can be seen, the graphs for nearly all the
projects roughly follow the same shape as the previous graph.

However, some of the projects exhibit different behaviors. We manually checked
two of them. The one represented by the blue straight line at top left turned
out to have code that was partially generated automatically from a .proto file
(Google’s protocol buffer file). These automatically generated functions all
had the default documentation string “Missing associated documentation comment
in .proto file”. As none of these words appeared in the function signatures,
they all got a meaningless score of 0, despite actually being meaningless. The
rest of the functions were constructors which received one argument, and had a
header comment stating what this argument was. These got a meaningless score
of 0.4.

The project represented by the pink line below that had 34 functions called
main with no arguments, which had verbose documentation including many
examples. They all got a meaningless score of 0, because the word “main” did
not appear.

We conclude that the projects that exhibit strange behaviors indeed contain
code that is not representative of normal programming by human developers.
However, there are only a small number of such projects, so their presence
does not have a significant impact on the validity of the general results.

##  6 Threats to Validity

Documentation is a wide-ranging topic. In the process of recruiting
participants on reddit we received several comments to the effect that our
survey did not and could not cover them all adequately. For example, one
participant noted that API documentation can never be complete because it is
impossible to anticipate all the needs users might have. Another noted that
the documentation requirements in different languages could be different: in
functional languages types are important, while in object oriented ones the
parameter explanations are the most useful. There were also reservations about
the survey itself, e.g. that we did not ask explicitly about side effects
being the most important thing missing in documentation. While some
participants added this and other considerations under “other”, it stands to
reason that more might have noted these considerations had they been presented
explicitly. The results are therefore probably biased against such
considerations. More generally, in various questions participants might have
made different assumptions concerning what exactly we were asking about,
leading to differences in answers.

Another concern is that our survey targeted developers and not projects. While
it would be surprising if we had multiple participants from the same project,
this could in principle happen. In any case, we cannot assume that the results
are statistically representative of the whole industry, and results on
percents of projects may be biased. Likewise, the empirical data collected
from GitHub was limited to projects in Python, and can not be assumed to even
represent all projects in this language.

Regarding the empirical evidence we collected, since we used a very simple
definition for “meaningless” score, it might be biased, and not capture the
real essence of meaningless function header documentation. We believe that
this study showed the potential of this methodology, and thus additional
effort needs to be put in the construction of a more sophisticated score for
meaningless documentation.

As such, we see our results as indicative for the answers to our research
questions, but concede that these results may be partial, as they might be
biased by the projects we chose and people that answered our survey. More
participants in the survey, and more projects to be analyzed, might show a
somewhat different picture, and are thus needed if one wishes to draw general
conclusions from this study.

##  7 Conclusions

Returning to our research questions, the answer to RQ1 is that header
functions are not universally used. About a quarter of our survey participants
reported that most of the functions in their project are documented, and a
similar fraction said that none are. But more than half said they turn to
header comments first when needing to understand a new function. Concerning
RQ2, the consensus was that output definition, examples, and parameters are
all useful and important (in this order), while inner methods are not. But in
RQ3 we found that examples were most often missing from the documentation. As
for RQ4, based on our GitHub sample we found that while most functions do not
have header comments, in those that do these comments do not just repeat
information that is already available in the function signature.

To conclude, we believe that function header documentation has an important
role in helping new developers to understand existing code, which is fulfilled
only partially in practice. This is due mainly to the large fraction of
projects and functions which do not have such documentation, and to sub-par
documentation which does not include examples. Thus, programmers might tend to
see header documentation as not worth the time investment in practice, both
when reading it (in new functions they did not write) and when writing it (in
projects they lead). And indeed, we found a mismatch between developers’
opinions that writing header comments is worth the effort and their actual
behavior of not always doing so.

However, our results also indicate that this state of affairs can be improved
with relatively little investment. A key observation is that not all functions
should be treated equally. It is important to apply judgment, and only
document functions that need it — either because they are part of an API or
because they are complex. An easy test is to verify that you have what to say
beyond the obvious from the function declaration. In these cases, it is
important to apply documentation guidelines which correspond to what
developers want and need, especially regarding the provision of examples of
usage. In other cases, where header documentation is not really needed, it
should be avoided, thereby reducing the overhead both for writers and for
readers, and at the same time focusing attention on those functions that _do_
have documentation — presumably for good reason.

## Experimental Materials

Experimental materials are available from Zenodo using DOI
10.5281/zenodo.10480939.

## References

  * [1] K. K. Aggarwal, Y. Singh, and J. Kumar, “An integrated measure of software maintainability”. In Proc. Ann. Reliability & Maintainability Symp., pp. 235–241, Jan 2002, DOI: 10.1109/RAMS.2002.981648.
  * [2] R. S. Alsuhaibani, C. D. Newman, M. J. Decker, M. L. Collard, and J. I. Maletic, “On the naming of methods: A survey of professional developers”. In 43rd Intl. Conf. Softw. Eng., pp. 587–599, May 2021, DOI: 10.1109/ICSE43902.2021.00061.
  * [3] M. Arab, “Enhancing program comprehension: Formatting and documenting”. SIGPLAN Notices 27(2), pp. 37–46, Feb 1992, DOI: 10.1145/130973.130975.
  * [4] D. M. Berry, K. Czarnecki, M. Antkiewicz, and M. AbdElRazik, “The problem of the lack of benefit of a document to its producer (PotLoBoaDtiP)”. In IEEE Intl. Conf. Softw. Sci., Tech. & Eng., pp. 37–42, Jun 2016, DOI: 10.1109/SWSTE.2016.14.
  * [5] S. Blinman and A. Cockburn, “Program comprehension: Investigating the effects of naming style and documentation”. In 6th Australasian User Interface Conf., pp. 73–78, Jan 2005.
  * [6] J. Börstler and B. Paech, “The role of method chains and comments in software readability and comprehension—an experiment”. IEEE Trans. Softw. Eng. 42(9), pp. 886–898, Sep 2016, DOI: 10.1109/TSE.2016.2527791.
  * [7] R. P. L. Buse and W. Weimer, “Synthesizing API usage exampes”. In 34th Intl. Conf. Softw. Eng., pp. 782–792, Jun 2012, DOI: 10.1109/ICSE.2012.6227140.
  * [8] H. Chen, Y. Huang, Z. Liu, X. Chen, F. Zhou, and X. Luo, “Automatically detecting the scopes of source code comments”. J. Syst. & Softw. 153, pp. 45–63, Jul 2019, DOI: 10.1016/j.jss.2019.03.010.
  * [9] M. E. Crosby, J. Scholtz, and S. Wiedenbeck, “The roles beacons play in comprehension for novice and expert programmers”. In 14th Workshop Psychology of Programming Interest Group, pp. 58–73, Jun 2002\.
  * [10] B. Curtis, S. B. Sheppard, E. Kruesi-Bailey, J. Bailey, and D. A. Boehm-Davis, “Experimental evaluation of software documentation formats”. J. Syst. & Softw. 9(2), pp. 167–207, Feb 1989, DOI: 10.1016/0164-1212(89)90019-8.
  * [11] B. Fluri, M. Würsch, and H. C. Gall, “Do code and comments co-evolve? on the relation between source code and comment changes”. In 14th Working Conf. Reverse Eng., pp. 70–79, Oct 2007, DOI: 10.1109/WCRE.2007.21.
  * [12] A. Head, C. Sadowski, E. Murphy-Hill, and A. Knight, “When not to comment: Questions and tradeoffs with API documentation for C++ projects”. In 40th Intl. Conf. Softw. Eng., pp. 643–653, May 2018, DOI: 10.1145/3180155.3180176.
  * [13] Y. Huang, M. Wei, S. Wang, J. Wang, and Q. Wang, “Yet another combination of IR- and neural-based comment generation”. Inf. & Softw. Tech. 152, art. 107001, Dec 2022, DOI: 10.1016/j.infsof.2022.107001.
  * [14] Z. M. Jiang and A. E. Hassan, “Examining the evolution of code comments in PostgreSQL”. In Working Conf. Mining Softw. Repositories, pp. 179–180, May 2006, DOI: 10.1145/1137983.1138030.
  * [15] D. Kramer, “API documentation from source code comments: A case study of JavaDoc”. In 17th Intl. Conf. Comput. Doc., pp. 147–153, Oct 1999, DOI: 10.1145/318372.318577.
  * [16] O. A. L. Lemos, M. Suzuki, A. C. de Paula, and C. Le Goes, “Comparing identifiers and comments in engineered and non-engineered code: A large-scale empirical study”. In 35th ACM Symp. Applied Computing, pp. 100–109, Mar 2020, DOI: 10.1145/3341105.3373972.
  * [17] T. C. Lethbridge, J. Singer, and A. Forward, “How software engineers use documentation: The state of the practice”. IEEE Softw. 20(6), pp. 35–39, Nov/Dec 2003, DOI: 10.1109/MS.2003.1241364.
  * [18] O. Levy and D. G. Feitelson, “Understanding large-scale software systems –- structure and flows”. Empirical Softw. Eng. 26(3), art. 48, May 2021, DOI: 10.1007/s10664-021-09938-8.
  * [19] B. Liskov and J. Guttag, Abstraction and Specification in Program Development. MIT Press, 1986.
  * [20] H. Malik, I. Chowdhury, H.-M. Tsou, Z. M. Jiang, and A. E. Hassan, “Understanding the rationale for updating a function’s comment”. In Intl. Conf. Softw. Maintenance, pp. 167–176, Sep 2008, DOI: 10.1109/ICSM.2008.4658065.
  * [21] S. McConnell, Code Complete. Microsoft Press, 2nd ed., 2004.
  * [22] M. Meng, S. Steinhardt, and A. Schubert, “How developers use API documentation: An observation study”. Commun. Des. Q. 7(2), pp. 40–49, Jul 2019, DOI: 10.1145/3358931.3358937.
  * [23] B. Meyer, “Applying “design by contract””. Computer 25(10), pp. 40–51, Oct 1992, DOI: 10.1109/2.161279.
  * [24] D. L. Parnas, “Software aging”. In 16th Intl. Conf. Softw. Eng., pp. 279–287, May 1994, DOI: 10.1109/ICSE.1994.296790.
  * [25] L. Prechelt, B. Unger-Lamprecht, M. Philippsen, and W. F. Tichy, “Two controlled experiments assessing the usefulness of design pattern documentation in program maintenance”. IEEE Trans. Softw. Eng. 28(6), pp. 595–606, Jun 2002, DOI: 10.1109/TSE.2002.1010061.
  * [26] S. Rai, R. C. Belwal, and A. Gupta, “A review on source code documentation”. ACM Trans. Intelligent Syst. & Tech. 13(5), art. 84, Jun 2022, DOI: 10.1145/3519312.
  * [27] M. P. Robillard, “What makes APIs hard to learn? answers from developers”. IEEE Softw. 26(6), pp. 27–34, Nov/Dec 2009, DOI: 10.1109/MS.2009.193.
  * [28] D. Steidl, B. Hummel, and E. Juergens, “Quality analysis of source code comments”. In 21st Intl. Conf. Program Comprehension, pp. 83–92, May 2013, DOI: 10.1109/ICPC.2013.6613836.
  * [29] G. Uddin and M. P. Robillard, “How API documentation fails”. IEEE Softw. 32(4), pp. 68–75, Jul/Aug 2015, DOI: 10.1109/MS.2014.80.
  * [30] C. Wang, H. He, U. Pal, D. Marinov, and M. Zhou, “Suboptimal comments in Java projects: From independent comment changes to commenting practices”. ACM Trans. Modeling & Comput. Simulation 32(2), art. 45, Apr 2023, DOI: 10.1145/3546949.
  * [31] R. Watson, M. Stamnes, J. Jeannot-Schroeder, and J. H. Spyridakis, “API documentation and software community values: A survey of open-source API documentation”. In 31st Intl. Conf. Design of Commun., pp. 165–174, Sep 2013, DOI: 10.1145/2507065.2507076.
  * [32] S. N. Woodfield, H. E. Dunsmore, and V. Y. Shen, “The effect of modularization and comments on program comprehension”. In 5th Intl. Conf. Softw. Eng., pp. 215–223, Mar 1981.