List:Internals« Previous MessageNext Message »
From:Konstantin Osipov Date:June 22 2009 3:34pm
Subject:Re: MySql coding style: Request for change regarding documentation.
View as plain text  
* Tor Didriksen <Tor.Didriksen@stripped> [09/06/22 17:53]:
> "function and method comments should be placed in front of
> implementation rather than declaration"
>
> I find it quite strange that member functions should be documented in
> the .cc file rather than the .h file, especially if these are public
> member functions (part of the public interface of the class).

We had this discussion already, opinions got split back then. 

There were two major reasons to keep comments close to
implementation:


1) This is how it was before we moved to doxygen, so we just
   updated syntax of most comments without moving them around.
   We try to preserve contingency of revision history when
   possible.
2) It was proclaimed back then that keeping comments closer to
   implementation would make them easier to maintain.

I personally don't have a strong opinion on the subject.
Sometimes, I put a comment in both places, a brief one in the
declaration, and a complete on in the implementation.
But I think changing the code to follow somewhat more widespread
and logical convention would be something  of lesser importance.

-- 
Thread
MySql coding style: Request for change regarding documentation.Tor Didriksen22 Jun
  • Re: MySql coding style: Request for change regarding documentation.Jay Pipes22 Jun
    • Re: MySql coding style: Request for change regarding documentation.Michael Widenius24 Jun
      • Re: MySql coding style: Request for change regarding documentation.MARK CALLAGHAN24 Jun
        • Re: MySql coding style: Request for change regarding documentation.Manyi Lu - Sun Norway25 Jun
      • Re: MySql coding style: Request for change regarding documentation.Tor Didriksen25 Jun
      • Re: MySql coding style: Request for change regarding documentation.Joerg Bruehe25 Jun
  • Re: MySql coding style: Request for change regarding documentation.Konstantin Osipov22 Jun
    • Re: MySql coding style: Request for change regarding documentation.MARK CALLAGHAN23 Jun
      • Re: MySql coding style: Request for change regarding documentation.Konstantin Osipov23 Jun
    • Re: MySql coding style: Request for change regarding documentation.Manyi Lu - Sun Norway23 Jun
      • Re: MySql coding style: Request for change regarding documentation.Konstantin Osipov23 Jun
  • Re: MySql coding style: Request for change regarding documentation.Guilhem Bichot22 Jun
  • Re: MySql coding style: Request for change regarding documentation.Dmitry Lenev22 Jun
    • Re: MySql coding style: Request for change regarding documentation.Tor Didriksen23 Jun
      • Re: MySql coding style: Request for change regarding documentation.Dmitry Lenev23 Jun
        • Re: MySql coding style: Request for change regarding documentation.Tor Didriksen23 Jun
      • Re: MySql coding style: Request for change regarding documentation.Michael Widenius24 Jun