List:Internals« Previous MessageNext Message »
From:Konstantin Osipov Date:June 23 2009 8:42am
Subject:Re: MySql coding style: Request for change regarding documentation.
View as plain text  
* MARK CALLAGHAN <mdcallag@stripped> [09/06/23 07:44]:
> > * 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.
> 
> From the proposal on refactoring, the code is about to undergo major
> changes.

We don't have a refactoring activity, unfortunately.
We have a re-engineering team/activity.

Differences are quite significant:

Refactoring is changing the code in small not-error prone steps
to achieve higher quality of the code.

Re-engineering is taking parts of code and rewriting them.
Essentially it's a re-write.

To say the least, I hope re-engineering is not going to do massive
changes in the code -- that'll be a disaster.

I'd be very welcoming refactoring of the code, but it is not
being done or planned.

Some references:

http://en.wikipedia.org/wiki/Code_refactoring
http://en.wikipedia.org/wiki/Reengineering_(software)
http://en.wikipedia.org/wiki/Rewrite_(programming) 

A very good definition (IMHO) of refactoring is here:

http://www.refactoring.com/

Refactoring is a disciplined technique for restructuring an
existing body of code, altering its internal structure without
changing its external behavior. Its heart is a series of small
behavior preserving transformations. Each transformation (called a
'refactoring') does little, but a sequence of transformations can
produce a significant restructuring. Since each refactoring is
small, it's less likely to go wrong. The system is also kept fully
working after each small refactoring, reducing the chances that a
system can get seriously broken during the restructuring.

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