Comments (9)
Hi, I've found that the codestyle is a bit vague in terms of the comments.
As we would like to use the Doxygen we have to decide which comment style is preferred.
Here you can find which comment styles can be processed by the Doxygen: https://www.stack.nl/~dimitri/doxygen/manual/docblocks.html
I think for multi lines comments there are two option:
- Java style:
\**
* @brief One liner description
*
* Description...
* @param example parameter
*\
\** One line description *\
- Qt style:
\*!
* \brief One liner description
*
* Description...
* \param example parameter
*\
\*! One line description *\
For me the Qt style seems nicer.
What do you think about it?
from gepard.
I'd prefer the Java style.
Are there any reasons why we should choose the Qt style?
from gepard.
It's just a personal preference, for me the Qt's tag style seems nicer. But as the qtcreator (also personal preference) supports both so I'd fine with the java as well (probably it is widely supported in other IDE-s).
So if there are no objection we should use the java style and update the coding style.
from gepard.
I've added the critical label to this because we should improve the coding style as it lacks of necessary guidelines at the moment.
First of all we should discuss how to add multiline function declaration, and what line length we should use.
from gepard.
I think the best way if we need to break a (too long) line then use one indentation (4 whitespace) style.
void Gepard::drawImage(Image /*image*/, float sx, float sy, float sw, float sh,
float dx, float dy, float dw, float dh)
{
const float veryVeryVeryLongName = (sx * sh - sy * sw) * (sx * sh - sy * sw)
+ (dx * dh - dy * dw) * (dx * dh - dy * dw);
const float anotherVeryVeryLongName = sqrt((sx * sw - sy * sh) * (sx * sw - sy * sh)
+ (dx * dw - dy * dh) * (dx * dw - dy * dh));
const float notSoLongName = sx + sy + sw + sh + dx + dy + dw + dh;
if (veryVeryVeryLongName + anotherVeryVeryLongName < notSoLongName
&& (veryVeryVeryLongName * anotherVeryVeryLongName > notSoLongName
|| veryVeryVeryLongName * anotherVeryVeryLongName * 2 > notSoLongName)
|| !notSoLongName)
return;
}
A note: use the break in the reasonable position.
from gepard.
It is a 2. draft:
// About the line breaking.
// Philosophy:
// 1. Long lines are not a problem.
// 2. If breaking a line is necessary, please use the following suggestions.
template<class T>
static inline const T& clamp(const T& value, const T& min, const T& max)
{
return (value < min) ?
min :
((value > max) ?
max :
value);
}
// Too long argument list.
// Arrange the arguments in reasonable groups (if it is possible).
void arc(Float x, Float y,
Float radius,
Float startAngle = 0.0f, Float endAngle = 2.0f * piFloat,
bool counterclockwise = false);
{
}
// If Doxygen comments are needed.
void Gepard::drawImage(Image image, /**< Image */
float sx = 0.0f, /**< Source x */
float sy = 0.0f, /**< Source y */
float sw = 0.0f, /**< Source width */
float sh = 0.0f, /**< Source height */
float dx = 0.0f, /**< Destination x */
float dy = 0.0f, /**< Destination y */
float dw = 0.0f, /**< Destination width */
float dh = 0.0f) /**< Destination height */
{
// Too long line.
// Arrange pieces in reasonable groups.
const float veryLongName = (sx * sh - sy * sw) * (sx * sh - sy * sw)
+ (dx * dh - dy * dw) * (dx * dh - dy * dw);
// Extremely long line.
const float anotherVeryVeryLongName =
sqrt((sx * sw - sy * sh) * (sx * sw - sy * sh)
+ (dx * dw - dy * dh) * (dx * dw - dy * dh));
if ((sx && sy && sw && sh && dx && dy && dw && dh)
&& ((sx - dx) && (sy - dy) && (sw - dw) && (sh - dh)))
return;
if (veryVeryVeryLongName + anotherVeryVeryLongName < notSoLongName
&& (veryVeryVeryLongName * anotherVeryVeryLongName > notSoLongName
|| veryVeryVeryLongName * anotherVeryVeryLongName * 2 > notSoLongName)
|| !notSoLongName)
return;
}
This is a work in progress version. But please review and comment it.
from gepard.
+1, I like the second one.
from gepard.
About the Doxygen style.
I started to use the Java_style and I have to agree with @kkristof in the Qt's style.
So I found the reason (what I was missing earlier) for choosing this style and it is the clarity.
from gepard.
@szledan yes, I agree. For me the Qt style is easier to read, but all of us should agree with that. So let's call a vote. We have +2 on the Qt style against the Java style. Please share your opinion. :)
from gepard.
Related Issues (20)
- Warning when calling 'delete' on an Xsurface created with 'new'
- Update the readme HOT 1
- Texture sampler isn't set
- Improve the Readme HOT 1
- Separate util implementations in gepard-types.cpp
- Remove gepard-types.h
- Create container classes for the vulkan resources
- Check the vulkan result where it is needed HOT 1
- Fix vulkan structure comments
- Improve the vulkan utility functions
- Vulkan backend can not load swapchain functions HOT 3
- Check the memory requirements in the vulkan implementation
- Seperate the extension function loading for the vulkan backend
- Rework backend HOT 2
- Check negative line width in stroke
- Milestone housekeeping
- Remove unnecessary ifdef guards
- Missing package HOT 2
- [meta] New design of the API
- Add Python binding HOT 1
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from gepard.