Skip to content

DOC: Add guideline on using a backslash as line continuation character #190

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
wants to merge 1 commit into
base: main
Choose a base branch
from
Draft
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
40 changes: 40 additions & 0 deletions SoftwareGuide/Latex/Appendices/CodingStyleGuide.tex
Original file line number Diff line number Diff line change
Expand Up @@ -62,6 +62,8 @@ \section{Overview}
argument lists.
\item \textbf{Ternary Operator}: accepted standards for using the ternary
operator.
\item \textbf{Backslashes}: guideline on using a backslash as line continuation
character.
\item \textbf{Using Standard Macros} (itkMacro.h): use of standard macros in
header files.
\item \textbf{Exception Handling}: how to add exception handling to the system.
Expand Down Expand Up @@ -3203,6 +3205,44 @@ \section{Ternary Operator}
And hence, the ternary operator is accepted in such cases.


\section{Backslashes}
\label{sec:Backslashes}

The use of a backslash as line continuation character appears to sometimes
hamper code readability. A backslash at the end of a line that has C++ \code{//}
comment may be quite confusing. For example, it may be overlooked easily that
the following code has commented out the \code{Sleep()} function call:

\small
\begin{minted}[baselinestretch=1,fontsize=\footnotesize,linenos=false,bgcolor=ltgray]{cpp}
// Wil we go to sleep or not? \
Sleep();
\end{minted}
\normalsize
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Although as the description says one may easily think that the above method will be called, I am not convinced why we should clarify this: this is not about ITK's style, but rather a C++/programming language feature. I would not even mention this. Has the situation been found in the recent PRs to ITK removing backslashes in the code?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for your feedback. My intention was to show two different cases for which the use of backslashes is problematic. In order to reach the conclusion that we discourage them in general (except for in macro definitions), in ITK C++ source code.

However, we could also just have a guideline specifically against backslashes in string literals. Without mentioning other possible cases. Is that what you prefer?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Although in other places the "recommended", "suggested", etc. words have been used (and this has also caused some debate), IMHO, in this case, as I said, a commit containing backslashes is unlikely to get accepted following your PRs in ITK, so to me, following your PRs and the improvement in style/message rendering they bring, "ITK does not use backslashes to break continuous string literals into multiple lines; it relies on its format enforcing tool -name it and cross ref- to break them." (or something similar with the same message; and then the macro stuff would come.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for your comments Jon, but...

a commit containing backslashes is unlikely to get accepted following your PRs in ITK

If that's the case, we might as well abandon this PR, right?

I thought it would be helpful to make it a guideline, because I encountered quite a few of those backslashes before doing ITK PR InsightSoftwareConsortium/ITK#3713. But if we may assume that those backslashes would not be accepted anymore now anyway, the guideline may not be necessary.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As you feel it Niels.


Moreover, the use of backslashes in a multiline string literal also appears
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Adjust the "Moreover (...) also" if we agree that the above content should be removed.

troublesome. For example, the following \code{badDescription} has all the space
characters of the indentation between "developers with " and "an extensive suite"
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LaTeX uses double backticks (open) + simple ticks (close) to render the quotes/literals.

embedded inside the string, which may not be intended. The definition of
\code{goodDescription} shows how to define such a lengthy string properly (as
the compiler concatenates adjacent string literals automatically).
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If I'm not mistaken, the literal might be automatically formatted/changed by the ITK style rules. So to me best would be to write the literal in a single line and let the code formatter do its job. If we agree on this, the above should be re-written .

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@jhlegarreta Would you like to rewrite the text or make another proposal yourself? Please feel free to make an alternative PR, if you want to, no problem.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I am fine if you amend the current commit following the comments.


\small
\begin{minted}[baselinestretch=1,fontsize=\footnotesize,linenos=false,bgcolor=ltgray]{cpp}
const char badDescription[] = "ITK is an open-source, cross-platform library that provides developers with \
an extensive suite of software tools for image analysis.";

const char goodDescription[] = "ITK is an open-source, cross-platform library that provides developers with "
"an extensive suite of software tools for image analysis.";
\end{minted}
\normalsize

So in general, the use of a backslash as line continuation character is
discouraged. Exception: a lengthy preprocessor macro definitions may actually
be more readable when it spans multiple lines, so in this case, the use of
backslashes is OK. But even then, such line continuation characters should not
appear inside a string literal.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So depending on my above comment, we should never use the backslash. It is not only discouraged: any PR that has one is likely to get a comment on it requesting to be changed.

I would put an example or cross-reference the appropriate section (if it exists, or maybe create one if it doesn't) concerning the marcos. Have not reviewed our definitions, but maybe we use the backslash always? Not sure what the rule has been/a pattern exists.

I comment on the style: I would rewrite the second sentence so that we integrated "Exception" into the sentence and would change "OK" for e.g. "accepted"/", ecommended".

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Backslashes are routinely used in macros, e.g. itkSimpleNewMacro.


\section{Using Standard Macros}
\label{sec:UsingStandardMacros}

Expand Down