Coding style discussion #3

Activity

1. szledan

   added

   question

   discussion

   documentation

   on Sep 19, 2015
2. kkristof commented on Apr 3, 2016

   

   kkristof

   on Apr 3, 2016

   Member

   More actions

   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?
3. szledan commented on Apr 4, 2016

   

   szledan

   on Apr 4, 2016

   MemberAuthor

   More actions

   I'd prefer the Java style.
   Are there any reasons why we should choose the Qt style?
4. kkristof commented on Apr 4, 2016

   

   kkristof

   on Apr 4, 2016

   Member

   More actions

   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.
5. kkristof

   added

   critical

   on Apr 14, 2016
6. kkristof commented on Apr 14, 2016

   

   kkristof

   on Apr 14, 2016

   Member

   More actions

   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.
7. szledan commented on Apr 14, 2016

   

   szledan

   on Apr 14, 2016

   Last edited by szledan

   MemberAuthor

   More actions

   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.
8. szledan commented on Apr 24, 2016

   

   szledan

   on Apr 24, 2016

   MemberAuthor

   More actions

   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.
9. dbatyai commented on Apr 24, 2016

   

   dbatyai

   on Apr 24, 2016

   Member

   More actions

   +1, I like the second one.
10. szledan commented on May 1, 2016

    

    szledan

    on May 1, 2016

    Last edited by szledan

    MemberAuthor

    More actions

    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.
11. kkristof commented on May 2, 2016

    

    kkristof

    on May 2, 2016

    Member

    More actions

    @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. :)
12. szledan

    added this to the continous milestone on Sep 17, 2016