«

Should comments in production software source code contain references to
in-house documents, or in my case, Bugzilla bugs? The argument for it is
that it makes it easier for developers to know what the code is about,
and customers who don't have access to in-house documents won't be
seeing the source code either. The argument against it is that source
code does not depend on, nor is tied to, in-house documents or Bugzilla
bugs. These in-house things could change, or even cease to exist,
without the source code having to be changed.

--
/-- Joona Palaste () ------------- Finland --------\
\-- http://www.helsinki.fi/~palaste --------------------- rules! --------/
"There's no business like slow business."
- Tailgunner

"Joona I Palaste" <> wrote in message
news:cbv0it$pf$...
> Should comments in production software source code contain references to
> in-house documents, or in my case, Bugzilla bugs? The argument for it is
> that it makes it easier for developers to know what the code is about,

> and customers who don't have access to in-house documents won't be
> seeing the source code either.

I'm not sure I understand this.

> The argument against it is that source
> code does not depend on, nor is tied to, in-house documents or Bugzilla
> bugs. These in-house things could change, or even cease to exist,
> without the source code having to be changed.
>

IMO something like javadoc is a good answer. The docs are embedded in the
code. The 'in-house docs' should be routinely extracted from the code and
this way things should stay in sync. However, these docs should be
relatively low-level in nature. Higher-level docs (ie: for end-users, or
docs on the overall system architecture) that may contain diagrams and
detailed formatting should not be referenced directly. On the other hand,
references to terms defined in these higher level docs may be appropriate as
long as you don't specify exact page numbers and such.



l8r, Mike N. Christoff

"Joona I Palaste" <> wrote in message
news:cbv0it$pf$...
> Should comments in production software source code contain references to
> in-house documents, or in my case, Bugzilla bugs? The argument for it is
> that it makes it easier for developers to know what the code is about,
> and customers who don't have access to in-house documents won't be
> seeing the source code either. The argument against it is that source
> code does not depend on, nor is tied to, in-house documents or Bugzilla
> bugs. These in-house things could change, or even cease to exist,
> without the source code having to be changed.
>

It might occasionally be useful if you have no other way of documenting
the bugs that the code refers to. But this is exactly what CVS checkin
comments
are for, and they don't live in your source files. Of course, then you need
some way
to get at the CVS comments...

-- Adam Maass

Joona I Palaste wrote:
> Should comments in production software source code contain references to
> in-house documents, or in my case, Bugzilla bugs? The argument for it is
> that it makes it easier for developers to know what the code is about,
> and customers who don't have access to in-house documents won't be
> seeing the source code either. The argument against it is that source
> code does not depend on, nor is tied to, in-house documents or Bugzilla
> bugs. These in-house things could change, or even cease to exist,
> without the source code having to be changed.

Personally, I'd say that the advantages when the information is useful
*vastly* outweigh the disadvantage when it's not (which I doubt is all
that common).

Michael Borgwardt wrote:
> Personally, I'd say that the advantages when the information is useful
> *vastly* outweigh the disadvantage when it's not (which I doubt is all
> that common).

There's another aspect to consider. When such a comment exists (i.e.,
this code fixes bug 27981), the piece of code is more likely to become
magic. Magic code (for those unfamiliar with the term) is code that is
there because it always has been and no one knows what would happen if
it were removed. Years later, it's often discovered that the magic code
wasn't really doing anything useful or that it became obsolete years
back; but magical code prevents change, since there's a superstition
that this piece of code can't be touched.

Far better (in an ideal world) would be to document the bug number near
the unit test, and leave the production code alone.

--
www.designacourse.com
The Easiest Way to Train Anyone... Anywhere.

Chris Smith - Lead Software Developer/Technical Trainer
MindIQ Corporation

"Chris Smith" <> wrote in message
news:.. .
> Michael Borgwardt wrote:
> > Personally, I'd say that the advantages when the information is useful
> > *vastly* outweigh the disadvantage when it's not (which I doubt is all
> > that common).
>
> There's another aspect to consider. When such a comment exists (i.e.,
> this code fixes bug 27981), the piece of code is more likely to become
> magic. Magic code (for those unfamiliar with the term) is code that is
> there because it always has been and no one knows what would happen if
> it were removed. Years later, it's often discovered that the magic code
> wasn't really doing anything useful or that it became obsolete years
> back; but magical code prevents change, since there's a superstition
> that this piece of code can't be touched.
>
> Far better (in an ideal world) would be to document the bug number near
> the unit test, and leave the production code alone.
>
> --
> www.designacourse.com
> The Easiest Way to Train Anyone... Anywhere.
>
> Chris Smith - Lead Software Developer/Technical Trainer
> MindIQ Corporation

On the other hand, it's not always magic... True story. I was doing
maintenance on an app that had been around for a long time. I found a line
in the thing that didn't seem to be executed and didn't do anything, just
loaded a register with itself. Being a conscientous programmer, I duly
commented the sucker out (we had a rule that any removed code was simply
commented out for at least 4 versions in case we had problems down the line.
Good policy.) Anyway, I recompiled that change and the ones I made and the
sucker wouldn't work. It traced it for a week. It wasn't my new code, that
was working like it should. Then I remembered the little useless line. I
uncommented that, recompiled and viola! It worked! Now I'm reallyconfused.
I look in the comment block at the beginning and see that the segment had
been written by my SENIOR DIRECTOR back at the dawn of time so I went to
talk to him. I asked if he remembered a certain program and he got this
funny smile on his face. Turns out that every programmer that ever touched
that program eventually came to talk to him about the exact problem I ran
into. The line was part of a routine in the original code but the feature
was moved elsewhere. When he deleted the routine, the rest of the thing
quit working. He added it back, and it started working again even though
that code section was never hit. A lot of time later, he narrowed it down
to just that one load register command that needed to be there and to this
day, no one knows why. I added a comment above the line "*Do not remove the
following line. Your segment won't work. We don't know why, it's just FM."

Joona I Palaste <> writes:

> Should comments in production software source code contain references to
> in-house documents, or in my case, Bugzilla bugs?

[....]

I have often seen programmers commenting out existing lines of
code, adding replacement lines and adding comments mentioning author
of the change and the bug number that required the change. This list
can get quite long and often switches back and forth.

I call this using source files as a bulletin board, with messages being
passed from one developer to another. As you can guess, I am not very
fond of this approach.

All this really should be handled by the by the IDE, which should show
me only what is relevent. http://mindprod.com/jgloss/scid.html and the
documents linkded from there talk about this in detail.

"Hemal Pandya" <hemalpandya-> wrote in message
news:...
> Joona I Palaste <> writes:
>
> > Should comments in production software source code contain references to
> > in-house documents, or in my case, Bugzilla bugs?
>
> [....]
>
> I have often seen programmers commenting out existing lines of
> code, adding replacement lines and adding comments mentioning author
> of the change and the bug number that required the change. This list
> can get quite long and often switches back and forth.
>
> I call this using source files as a bulletin board, with messages being
> passed from one developer to another. As you can guess, I am not very
> fond of this approach.
>
> All this really should be handled by the by the IDE, which should show
> me only what is relevent. http://mindprod.com/jgloss/scid.html and the
> documents linkded from there talk about this in detail.

I have to disagree with your assessment of the practice. I guess if the
developers you're seeing aren't up to snuff, then, yes, the practice could
get tedious. If you have that kind of situation, it seems to me that the
problem is not being addressed. But good coding practices and code
walkthrus can eliminate a lot of the back and forth you talk about. My
experience has shown that the practice of commenting out code rather than
deleting it has actually eliminated a lot of problems. It doesn't disguise
the tracks of the previous programmers so you know the history of the
changes.

On Thu, 1 Jul 2004 09:36:35 -0600, "Robert B."
<> wrote or quoted :

> I added a comment above the line "*Do not remove the
>following line. Your segment won't work. We don't know why, it's just FM."

In the C++ days, code could be magic BECAUSE it did nothing. If
something clobbered it with a wild pointer for example, it did no
harm. Sometimes random bits of code would just shift things around
enough to change the values of uninitialised variables.

Strangely, there are folk nostalgic for those days.

--
Canadian Mind Products, Roedy Green.
Coaching, problem solving, economical contract programming.
See http://mindprod.com/jgloss/jgloss.html for The Java Glossary.

In article <>,
Chris Smith <> wrote:
>
>There's another aspect to consider. When such a comment exists (i.e.,
>this code fixes bug 27981), the piece of code is more likely to become
>magic.

Another disadvantage is that it can easily lead to the programmer
_only_ writing "see bug#1234" and nothing else in the comment when he
might otherwise have written "this fixes printing on HP printers" or
somesuch. Once the reference to bug#1234 becomes obsolete for some
reason (bug database unavailable, or discontinued, or whatever), the
comment becomes useless whileas the
short-and-to-the-point-but-not-exhaustive comment would still remain
useful.

The solution to this problem, of course, is to write "this fixes
printing on HP printers (bug#1234)" but the question is whether or not
this is actually going to happen.

Cheers
Bent D
--
Bent Dalager - - http://www.pvv.org/~bcd
powered by emacs