[OT?] Commenting question

Discussion in 'Java' started by Joona I Palaste, Jun 30, 2004.

  1. 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, Jun 30, 2004
    #1
    1. Advertising

  2. "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
     
    Michael N. Christoff, Jun 30, 2004
    #2
    1. Advertising

  3. Joona I Palaste

    Adam Maass Guest

    "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
     
    Adam Maass, Jul 1, 2004
    #3
  4. 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, Jul 1, 2004
    #4
  5. Joona I Palaste

    Chris Smith Guest

    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, Jul 1, 2004
    #5
  6. Joona I Palaste

    Robert B. Guest

    "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."
     
    Robert B., Jul 1, 2004
    #6
  7. Joona I Palaste

    Hemal Pandya Guest

    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, Jul 1, 2004
    #7
  8. Joona I Palaste

    Robert B. Guest

    "Hemal Pandya" <> 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.
     
    Robert B., Jul 1, 2004
    #8
  9. Joona I Palaste

    Roedy Green Guest

    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.
     
    Roedy Green, Jul 1, 2004
    #9
  10. 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
     
    Bent C Dalager, Jul 1, 2004
    #10
  11. Joona I Palaste

    Roedy Green Guest

    On Thu, 1 Jul 2004 11:01:52 -0600, "Robert B."
    <> wrote or quoted :

    >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

    --
    Canadian Mind Products, Roedy Green.
    Coaching, problem solving, economical contract programming.
    See http://mindprod.com/jgloss/jgloss.html for The Java Glossary.
     
    Roedy Green, Jul 2, 2004
    #11
  12. Joona I Palaste

    Robert B. Guest

    "Roedy Green" <> wrote in message
    news:...
    > On Thu, 1 Jul 2004 11:01:52 -0600, "Robert B."
    > <> wrote or quoted :
    >
    > >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.
    >


    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...
     
    Robert B., Jul 2, 2004
    #12
  13. Michael N. Christoff <> coughed up the
    following:
    > "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.



    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.
     
    Thomas G. Marshall, Jul 7, 2004
    #13
  14. "Thomas G. Marshall" <>
    wrote in message news:lxKGc.7401$...
    > Michael N. Christoff <> coughed up the
    > following:
    > > "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.

    >
    >
    > I don't think that answers his question.
    >


    I was referring to this:

    > >> Should comments in production software source code contain
    > >> references to in-house documents...


    > 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
     
    Michael N. Christoff, Jul 7, 2004
    #14
  15. Michael N. Christoff <> coughed up the
    following:
    > "Thomas G. Marshall"
    > <> wrote in
    > message news:lxKGc.7401$...
    >> Michael N. Christoff <> coughed up
    >> the following:
    >>> "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.

    >>
    >>
    >> I don't think that answers his question.
    >>

    >
    > I was referring to this:
    >
    >>>> Should comments in production software source code contain
    >>>> references to in-house documents...

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


    {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.
     
    Thomas G. Marshall, Jul 7, 2004
    #15
    1. Advertising

Want to reply to this thread or ask your own question?

It takes just 2 minutes to sign up (and it's free!). Just click the sign up button to choose a username and then you can ask your own questions on the forum.
Similar Threads
  1. vijay
    Replies:
    7
    Views:
    13,755
    Jim Lewis
    Feb 7, 2005
  2. =?Utf-8?B?U2FuZHk=?=

    Commenting out VB code

    =?Utf-8?B?U2FuZHk=?=, Feb 2, 2005, in forum: ASP .Net
    Replies:
    5
    Views:
    51,855
    =?Utf-8?B?Sm9uWg==?=
    Feb 3, 2005
  3. Commenting in Java

    , Aug 26, 2005, in forum: Java
    Replies:
    38
    Views:
    1,128
    Chris Uppal
    Sep 4, 2005
  4. Replies:
    1
    Views:
    337
  5. patrick

    java commenting out of code

    patrick, Jan 11, 2006, in forum: Java
    Replies:
    4
    Views:
    5,222
    Malte Christensen
    Jan 11, 2006
Loading...

Share This Page