DOC: Add "Integer Type Specifiers" section#183
DOC: Add "Integer Type Specifiers" section#183thewtex merged 1 commit intoInsightSoftwareConsortium:masterfrom
Conversation
github-actions
bot
added
area:Appendices
|
Excellent. Is this the right section to also state that when each is needed |
Thanks for the suggestion, but I think this should be in a different section. Because the section I'm proposing here is specifically about integer types. |
For when we do include that information, there's a page that suggests the order for even more categories: attributes-friendness-storage-constness-virtualness-explicitness-signedness-length-type. |
@jhlegarreta Thanks for you comment, Jon. Would those single "backtick" quotes that I'm using here (``) cause LaTeX syntax errors, or it is only a matter of style? Many other applications support those backticks for code, including GitHub/MarkDown: https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#quoting-code |
|
Just in case it isn't clear from the previous posts here ... my summary: LaTeX wants it to be a pair of single back ticks and then a pair of single forward ticks: if the goal is to put it in double quotes. If instead the goal is to use a fixed-width font then the likes of is defined for this document. |
@N-Dekker Lee's comment explains it: we are not writing Markdown text here, but LaTeX text. The single backticks in LaTeX do not translate into any markup/highlighting, and thus, if the text within single backticks is intended to be highlighted somehow (as it is the case), using single backticks has no effect. |
N-Dekker
force-pushed
the
IntegerTypeSpecifiers
branch
from
8ddd3d6 to
c000be8
Compare
Very interesting, thanks Lee, but again, I feel it's beyond the scope of this particular pull request. If you feel like preparing another PR specifically on keyword ordering, feel free to do so 😃 |
|
build-publish-pdf is still failing, after having fixed the quotes and double-quotes (hereby force-pushed), as requested by @jhlegarreta and @Leengit It says:
Does anyone have a clue? |
|
ITKDevelopmentEnvironment seems to be building the nightly one. The last one errored out, #184 is an attempt to address that. |
|
I took a look at the build log. Here is an abbreviated version: |
| \label{subsec:IntegerTypeSpecifiers} | ||
|
|
||
| Throughout the code base, the built-in type \code{unsigned int} is spelled exactly like that: | ||
| ``unsigned int'' (rather than just ``unsigned''). Other built-in integer types should in |
There was a problem hiding this comment.
Thanks for the effort @N-Dekker. Why are some types left with quotes instead of consistently using the \code{} markup? To me, these are programming types/constructs not found in English language (as a whole) that deserve such highlighting.
There was a problem hiding this comment.
@jhlegarreta Thanks for asking. I did deliberately make a choice between \code{...} and double-quotes, each time. You see, this section specifically deals with how to spell a certain type.
-
\code{unsigned int}refers to the C++ type itself -
"unsigned int" refers to the way we spell it (according to our Style Guide).
Both spellings, "unsigned" and "unsigned int" denote the very same C++ type, unsigned int.
Hope that answers your question. 😃
There was a problem hiding this comment.
Still not convinced. If others think it is OK as it is, then it's maybe a very personal view of mine, and the conversation can be resolved.
There was a problem hiding this comment.
If others think it is OK ...
Whichever. I am willing to defer to the person doing the work.
|
In a way, this guideline treats "unsigned int" versus "unsigned" different than "signed long int" versus "long". Personally I would have preferred to consistently always use the shortest form (just "unsigned", like we do just "long"), but there appeared no consensus for just "unsigned", at PR InsightSoftwareConsortium/ITK#3139. So this guideline aims to describe the current ITK coding convention, not necessarily my personal preference 😺 I'm just saying so, because it's different from most of my other pull requests, which are usually mostly according to my preference 😄 No need to redo the "unsigned int" versus "unsigned" discussion right now. |
N-Dekker
force-pushed
the
IntegerTypeSpecifiers
branch
from
c000be8 to
0487224
Compare
|
FYI, My most recent amend (force-push) is just a |
N-Dekker
force-pushed
the
IntegerTypeSpecifiers
branch
from
0487224 to
f0cc03c
Compare
github-actions
bot
added
the
type:Documentation
| facilities (like \code{<cstdlib>} and \code{<cstdint>}) should generally be used without a \code{std::} prefix. | ||
| For example, ``size_t'', ``int8_t'', and ``uintmax_t'' are preferred to ``std::size_t'', | ||
| ``std::int8_t'', and ``std::uintmax_t''. When using any of those type aliases, the ITK header file | ||
| ``itkIntTypes.h'' may need to be \code{#include}d, to ensure that those types are declared within the |
There was a problem hiding this comment.
Perhaps the # needs to be escaped?
There was a problem hiding this comment.
For the record, the underscores needed to be escaped! For example, "size_t" needed to be spelled size\_t
N-Dekker
force-pushed
the
IntegerTypeSpecifiers
branch
from
f0cc03c to
a49725e
Compare
Added coding style guidelines for specifying built-in integer types and integer types from the C library. Following recent ITK commits, authored by Lee Newberg: pull request InsightSoftwareConsortium/ITK#3365 commit InsightSoftwareConsortium/ITK@8c2c654 commit InsightSoftwareConsortium/ITK@e03a941 "STYLE: Drop `signed` and `int` from some types" pull request InsightSoftwareConsortium/ITK#3139 commit InsightSoftwareConsortium/ITK@a812aa3 "STYLE: Change unsigned to unsigned int." pull request InsightSoftwareConsortium/ITK#3250 commit InsightSoftwareConsortium/ITK@c173dfd "STYLE: Remove `std::` prefix from types that work without it"
N-Dekker
force-pushed
the
IntegerTypeSpecifiers
branch
from
a49725e to
612adf5
Compare
5 participants
Added coding style guidelines for specifying built-in integer types and
integer types from the C library.
Following recent ITK commits, authored by Lee Newberg (@Leengit):
pull request InsightSoftwareConsortium/ITK#3365
commit InsightSoftwareConsortium/ITK@8c2c654
commit InsightSoftwareConsortium/ITK@e03a941
"STYLE: Drop
signedandintfrom some types"pull request InsightSoftwareConsortium/ITK#3139
commit InsightSoftwareConsortium/ITK@a812aa3
"STYLE: Change unsigned to unsigned int."
pull request InsightSoftwareConsortium/ITK#3250
commit InsightSoftwareConsortium/ITK@c173dfd
"STYLE: Remove
std::prefix from types that work without it"