Skip to content

Document classes and member variables unless obvious #2708

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.

Sign up for GitHub

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

Merged
merged 2 commits into from
Aug 10, 2018
Merged

Document classes and member variables unless obvious #2708

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
611374f
Document classes and member variables unless obvious
Aug 10, 2018
519370d
State that identifiers should be good
Aug 10, 2018
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
12 changes: 7 additions & 5 deletions CODING_STANDARD.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -59,12 +59,13 @@ Formatting is enforced using clang-format. For more information about this, see
```
Note that the `\file` tag must be immediately followed by a newline in order
for Doxygen to relate the comment to the current file.
- Each function should be preceded by a Doxygen comment describing that
function. The format should match the [LLVM
- Each class, member variable and function should be preceded by a Doxygen
comment describing it when it is not immediately obvious what it does. The
format should match the [LLVM
Copy link
Collaborator

Choose a reason for hiding this comment

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

Maybe we also need an explicit note that {class,member,function} names must make clear their purpose?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

I've added a commit doing this, but in the Naming section below

guidelines](http://llvm.org/docs/CodingStandards.html#doxygen-use-in-documentation-comments),
with one extension: `\param` and `\return` comments longer than a single line
should have subsequent lines indented by two spaces, so that the tags stand
out. An example:
with one extension: for functions, `\param` and `\return` comments longer than
a single line should have subsequent lines indented by two spaces, so that the
tags stand out. An example:
```c++
/// This sentence, until the first dot followed by whitespace, becomes
/// the brief description. More detailed text follows. Feel free to
Expand Down Expand Up @@ -93,6 +94,7 @@ Formatting is enforced using clang-format. For more information about this, see
- Use #ifdef DEBUG to guard debug code

# Naming
- Identifiers should make clear the purpose of the thing they are naming.
- Identifiers may use the characters `[a-z0-9_]` and should start with a
lower-case letter (parameters in constructors may start with `_`).
- Omit names of parameters or exception objects when they are not used. If
Expand Down