[WIP] Coding Style Guide #3026
[WIP] Coding Style Guide #3026
Conversation
Explain when using auto is acceptable
|
@amin1377 Any comments on what should be added to this guide is appreciated. |
|
Fully agree with the usage of auto as documented here. I guess we also should talk about the naming schemes we use. What I personally extrapolated from the code base and remember currently is that Classes are PascalCase, everything else is snake_case, structs are trivial and C-like and start with t_ but it should all be written down. One more thing is saying that people should prioritize (but not blindly use in all circumstances) using vtr:: containers over STL and use the various LOG/ERROR macros over directly using printf/cout. |
There was a problem hiding this comment.
Hi Soheil, thank you so much for starting to add documentation on coding style! This is extremely important for such a large project such as VTR.
I think the coding style that we tell the students in ECE297 will be a good reference for a checklist of things to add to this documentation:
tutorial5_code_style.pdf
Specifically this slide:
I think the major things that are missing are:
- The variable, function, and classes naming conventions that we use in VTR
- Keeping function short (i.e. pulling out code into helper methods)
- Self-checking code (i.e. proper use of VTR_ASSERT)
I think the three above are very important to document since we can point people to this page if they raise a PR that does not have proper style; since I believe these three things (as well as the things you have documented) would block a PR from being merged in my opinion!
I know our goal is to keep this style guide brief; but if you would like more things to add to the style guide, I can point you to some of the different style guides that I am familiar with!
|
|
||
| .. code-block:: cpp | ||
|
|
||
| class Example { |
There was a problem hiding this comment.
Note: this convention is not followed very consistently today but we should move to it.
There was a problem hiding this comment.
Or maybe we just say that at the top of the style guide.
| ------------- | ||
|
|
||
| - Focus on explaining *why* the code exists or behaves in a certain way. | ||
| - Do not explain *what* the code is doing if it's already clear from the code itself. |
There was a problem hiding this comment.
.h file should say what the code does; if not obvious explain why the code behaves that way as well.
.cpp file should explain how the code works if it is not obvious.
|
|
||
| Comment types and rules: | ||
|
|
||
| - Use `/* ... */` **only** for Doxygen documentation comments. |
There was a problem hiding this comment.
I'd weaken this a bit / explain the reasoning. Seem a bit strong on the /* vs. //
|
|
||
|
|
||
|
|
||
|
|
There was a problem hiding this comment.
Other guidelines:
- Prefer short functions, so they can be reused and their purpose can be more easily commented.
- Avoid unnecessary use of complex language features; prefer easier-to-read code
- Check the code and documentation at to see if a utility or routine already exists before making a new one
- Group related data into structs or classes, and comment each data member and member function
There was a problem hiding this comment.
assertion guidelines:
- use assertions and data structure validators wherever possible.
- In CPU-critical code, use VTR_ASSERT_SAFE for potentially expensive checks
<link>
| - Do not explain *what* the code is doing if it's already clear from the code itself. | ||
| - Keep comments up to date. Outdated comments are worse than no comments. | ||
| - Use Doxygen-style `/** ... */` or `///` for documenting APIs, classes, structs, members, and files. | ||
|
|
There was a problem hiding this comment.
Follow the instructions at <link> to add new utilities, APIs or internal functionality doxygen documentation to the html pages at <link>.
Addresses #2678