Loading ...
Sorry, an error occurred while loading the content.

Re: [XP] Signing Your Work vs Code Ownership

Expand Messages
  • Ron Jeffries
    ... I agree with that statement and am concerned about what it leaves unsaid. It doesn t address /why/ we want to sign the code, nor does it address whether
    Message 1 of 78 , Feb 1, 2002
    • 0 Attachment
      Around Friday, February 01, 2002, 5:54:41 AM, gorowitch wrote:

      >> If you want to sign your work because you're proud of it, go for it.
      >>

      > Thanks,
      > Can we agree upon:

      > "Signing Your Work" doesn't have to imply "Code Ownership" ?

      I agree with that statement and am concerned about what it leaves
      unsaid. It doesn't address /why/ we want to sign the code, nor does it
      address whether /we/ want to sign /our/ code (ownership) or we wish
      /he/ would sign /his/ code (something else).

      I'd have to write a bit to know what I'd really say, but it would be
      something like:

      By all means be proud enough of your work to be willing to sign it,
      and in fact do sign it if it helps you or makes you feel good.
      Beware of signing as a form of marking someone's territory, or as a
      warning that you are about to step in something. If you think you
      /need/ signatures, there may be some other problem. Find and fix
      that.

      >> If you think you /need/ signatures, there's some other problem.
      >> Fix that.

      > Again agreed.

      > Author tags aren't really needed. I still believe they can be usefull
      > though. But perhaps the disadvantages outweigh the possible
      > advantages.

      I don't know. I'm not against them. I rather like the notion of
      signing something with pride in its creation. I'm not sure author tags
      would give me that particular thrill.

      Otherwise, I'm just asking questions.

      Ron Jeffries
      www.XProgramming.com
      You keep using that word. I do not think it means what you think it means.
      --Inigo Montoya
    • Jim Standley
      This has been a very long thread already, so I ll try to weigh in quickly with a few practices that have made us happy. When modifying code significantly add a
      Message 78 of 78 , Feb 4, 2002
      • 0 Attachment
        This has been a very long thread already, so I'll try to weigh in quickly
        with a few practices that have made us happy.

        When modifying code significantly add a comment. Always put it in the
        method header, sometimes duplicated in the code if it's a long method and
        it's not obvious what I did. Our standard format is:

        // mm/dd/yyyy My Name Did so and so.

        When appropriate include a defect report reference, or a story or use case.

        // mm/dd/yyyy CQ1234 My Name Did something else

        When checking in code, put a similar comment in the VC tool comments. On
        one project I made a browser for VC comments and ran it daily to see what
        had been going on in the code lately. It linked into the VC diff tool and a
        code browser to make monitoring progress easy.

        In Java we omit the @author tag. The author is of very little interest when
        reading API docs to see what something does. For new classes, we use the
        same comment format, but the "did what" just says "New".

        The main value of all this in the code is to help somebody who revisits code
        they haven't seen in a while and asks "What the heck happened while I wasn't
        looking!" A little explanation of the reason for a change goes a long way.
        If it doesn't go far enough, the author may still be around to ask. We've
        also found it useful when a user asks "How long has it been doing this?"
        whether it's a good thing or a bad thing that it's doing.

        I think these comments work regardless of your concepts of ownership and
        responsibility by group or individual. I try to always write things I'm
        happy to put my name on. If I'm not happy, it's a tip to rethink the code.
        Of course in the end I'm not above putting in comments like "This section
        compromises x to optimize y." or a favorite "I have no idea why this works
        but it avoids bug a in window z."
      Your message has been successfully submitted and would be delivered to recipients shortly.