[OT?] Commenting question

[Joona I Palaste]

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.

 

[Michael N. Christoff]

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

 

[Adam Maass]

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

 

[Michael Borgwardt]

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

 

[Chris Smith]

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

 

[Robert B.]

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

 

[Hemal Pandya]

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.

 

[Robert B.]

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.

 

[Roedy Green]

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.

 

[Bent C Dalager]

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

 

[Roedy Green]

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.

what is the alternative? Jira is one where you track all this stuff
with issues, subissues and endless comments, but everything trackable
and sorted out. At least it keeps it out of the source code, and gives
the boss an easy way to see what is still outstanding. Not that
popular with programmers though since you are supposed to make an
entry every time you blow you nose.




See http://mindprod.com/jgloss/jira.html

 

[Robert B.]

what is the alternative? Jira is one where you track all this stuff
with issues, subissues and endless comments, but everything trackable
and sorted out. At least it keeps it out of the source code, and gives
the boss an easy way to see what is still outstanding. Not that
popular with programmers though since you are supposed to make an
entry every time you blow you nose.

If you keep the information in the file that it pertains to, it won't get
lost. You might be right when you're talking smaller companies, but it
won't work for big ones. The problem is that no one in a big company wants
to get together to establish a single software set to do development. It's
a political thing and everyone whats to set the rules in their own kingdoms.
Then, even if you do get a miracle and some standard platform DOES get
decided on, then you have upgrades that won't take the data from previous
versions, the vendor goes out of business or sunsets your product, or
something from another vendor comes along that's a lot better and you can't
use it because it's incompatible with the old stuff or you do use it and
lose all your history. Don't laugh. I've seen all the above scenarios
develop and it's not pretty. If the information goes in the source code
file, then you don't have to worry about any of that. That seems to be the
only bullet-proof solution. We've done that, using some coding standards,
and only have to write little in-house tools to strip out program data and
feed them into our tools. We've found that only the marketing folks and
upper management follow problems in the tracking tools anyway. The
developers prefer to look at the source...

 

[Thomas G. Marshall]

I'm not sure I understand this.


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.

I don't think that answers his question.

Sure, he can use javadoc, but in the comments /used by/ javadoc (the ones in
the code using javadoc tags), should he make references to bugzilla in-house
entries, etc.?

I suspect that if there were even a smidgeon of a chance that the exterior
documentation could change in any way then my answer would be so loud a "no"
that you would soil yourself.

 

[Michael N. Christoff]

I don't think that answers his question.

I was referring to this:

Sure, he can use javadoc, but in the comments /used by/ javadoc (the ones in
the code using javadoc tags), should he make references to bugzilla in-house
entries, etc.?

I suspect that if there were even a smidgeon of a chance that the exterior
documentation could change in any way then my answer would be so loud a "no"
that you would soil yourself.

That's nice. I worked on an application that, among other things, allowed
users to define business processes composed of discrete sub-tasks. Although
the implementation and docs would change over time, the idea of (as
explained in the user docs) processes and sub-tasks did not. They were
essentially "application invariants".



l8r, Mike N. Christoff

 

[Thomas G. Marshall]

"Thomas G. Marshall"


I was referring to this:



That's nice.

{chuckle} sorry.

I worked on an application that, among other things,
allowed users to define business processes composed of discrete
sub-tasks. Although the implementation and docs would change over
time, the idea of (as explained in the user docs) processes and
sub-tasks did not. They were essentially "application invariants".

Ok, well there's a line to be drawn somewhere I suppose.

But IMO, referring to document XYZ within the code is dangerous since
documents change, even their overall intent, and documents change names.