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