b***@bugs.documentfoundation.org
2015-04-24 13:55:26 UTC
https://bugs.documentfoundation.org/show_bug.cgi?id=90834
Bug ID: 90834
Summary: Turn in-line version control history comments into
meaningful good comments
Product: LibreOffice
Version: 4.5.0.0.alpha0+ Master
Hardware: Other
OS: All
Status: UNCONFIRMED
Severity: minor
Priority: medium
Component: LibreOffice
Assignee: libreoffice-***@lists.freedesktop.org
Reporter: ***@iki.fi
Especially in sw we have lots of comments, mainly by a person called "OD", but
possibly also others, inherited from OpenOffice.org times, that go like this:
// OD 06.08.2002 #99657# - add 6th parameter to indicate,
if
// background transparency have to be considered
// Set missing 5th parameter to the default value
GRFNUM_NO
// - see declaration in /core/inc/frmtool.hxx.
These basically are in-line version control comments: They tell what change was
done to the code at that date, and by whom. That is not information that should
be in the source code (but recorded in the version control system). When
possible, such comments should be changed to tell what the code does, using the
present tense. The above could turn into something like:
// The 6th parameter indicates if
// background transparency have to be considered.
// See declaration in /core/inc/frmtool.hxx.
In other cases, like:
// OD 05.09.2002 #102912#
// delete temporary background brush.
delete pTmpBackBrush;
it's just the timestamp and bug number that should be removed. They are not
interesting.
// delete temporary background brush.
delete pTmpBackBrush;
In cases like:
// --> OD #i102707#
namespace
{
...
}
// <--
the comments are not useful at all and should simply be deleted.
Obviously exactly what to do with these "OD" comments is a matter of taste...
If you plan to work on it, please submit an initial suggestion with perhaps a
dozen or so comments handled for review, before wasting time on doing hundreds
of cases in perhaps the "wrong" way.
Bug ID: 90834
Summary: Turn in-line version control history comments into
meaningful good comments
Product: LibreOffice
Version: 4.5.0.0.alpha0+ Master
Hardware: Other
OS: All
Status: UNCONFIRMED
Severity: minor
Priority: medium
Component: LibreOffice
Assignee: libreoffice-***@lists.freedesktop.org
Reporter: ***@iki.fi
Especially in sw we have lots of comments, mainly by a person called "OD", but
possibly also others, inherited from OpenOffice.org times, that go like this:
// OD 06.08.2002 #99657# - add 6th parameter to indicate,
if
// background transparency have to be considered
// Set missing 5th parameter to the default value
GRFNUM_NO
// - see declaration in /core/inc/frmtool.hxx.
These basically are in-line version control comments: They tell what change was
done to the code at that date, and by whom. That is not information that should
be in the source code (but recorded in the version control system). When
possible, such comments should be changed to tell what the code does, using the
present tense. The above could turn into something like:
// The 6th parameter indicates if
// background transparency have to be considered.
// See declaration in /core/inc/frmtool.hxx.
In other cases, like:
// OD 05.09.2002 #102912#
// delete temporary background brush.
delete pTmpBackBrush;
it's just the timestamp and bug number that should be removed. They are not
interesting.
// delete temporary background brush.
delete pTmpBackBrush;
In cases like:
// --> OD #i102707#
namespace
{
...
}
// <--
the comments are not useful at all and should simply be deleted.
Obviously exactly what to do with these "OD" comments is a matter of taste...
If you plan to work on it, please submit an initial suggestion with perhaps a
dozen or so comments handled for review, before wasting time on doing hundreds
of cases in perhaps the "wrong" way.
--
You are receiving this mail because:
You are the assignee for the bug.
You are receiving this mail because:
You are the assignee for the bug.