List:Internals« Previous MessageNext Message »
From:Konstantin Osipov Date:June 23 2009 10:06am
Subject:Re: MySql coding style: Request for change regarding documentation.
View as plain text  
* Manyi Lu - Sun Norway <Manyi.Lu@stripped> [09/06/23 13:59]:
>>> "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.
>>   
> Now that we have moved to doxygen, shouldn't the standard be adapted to  
> reflect that?

The coding standard reflects the fact that we moved to doxygen.

>> 2) It was proclaimed back then that keeping comments closer to
>>    implementation would make them easier to maintain.
>>   
> I would expect it is easier to maintain comments describing the  
> interface if they are placed where the interface are declared. The same  
> applies to keeping comments related to implementation close to where the  
> implementations are.
>
> I wonder when/how will the change requests proposed by Tor be handled in  
> the coding style committee?

I hope we will meet this week for the first time.

-- 
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