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

Re: Documentation for code. Do we need Colective ownership because it is imposible to document code to an understandable state for anyone...

Expand Messages
  • strazhce
    Hi, Gustavo, I could give you my point of view as a programmer. ... If you have 1 programmer working on the project and he will leave soon, then get his
    Message 1 of 4 , May 30, 2011
    • 0 Attachment
      Hi, Gustavo,

      I could give you my point of view as a programmer.

      --- In extremeprogramming@yahoogroups.com, Gustavo Cebrian Garcia <g.cebrian.garcia@...> wrote:
      >
      > Do you get my idea? In a scenario where just a programmer is working on a
      > project, how much documentation is needed in case
      > that programmer is going to leave in a few months?
      If you have 1 programmer working on the project and he will leave soon, then get his replacement working with him ASAP. No written documentation will replace direct knowledge transfer.

      > And, if we have a team with colective ownership, it is necessary to document
      > the code?
      What is Collective Ownership from your point of view?


      As a programmer I would say Always document the code. I hate seeing a class without any word of why this class is here and how it is special.
      Now the question is how much. At least document class purpose. Then document important and complex methods (e.g. if methods call many other methods, which call other methods etc.). My preferred methods of documentation:
      - javadoc or equivalent for classes
      - concise tests for methods
      - javadoc for methods

      Then I need some roadmap - highlevel overview of main design concepts and main class names. Short and to the point. No details, which would change often.

      Just my point of view. I hope this helped.

      Oleg
    • Steven Gordon
      Whether or not there is collective ownership, I do not find reams of prose documentation at all helpful in picking up the code base of an existing project.
      Message 2 of 4 , May 30, 2011
      • 0 Attachment
        Whether or not there is collective ownership, I do not find reams of prose
        documentation at all helpful in picking up the code base of an existing
        project.

        Reams of prose will mix up three different states of the code base:

        1. What was supposed to be (i.e., the future state).
        2. What was true at one time (i.e., some past state).
        3. What is true now (i.e., the current state).

        These different kinds of "truth" does not even factor in the misstatements
        and ambiguities inherent to prose documentation.

        Then, there is the extra cost of the prose documentation, because every
        change to the code has to be accurately reflected in the prose
        documentation. This means searching the documentation for every place that
        the change affected. Unless we do this, problem 2 above gets worse and
        worse over time. This can more than double the cost of change (and will
        often discourage us from making many good changes for which the extra cost
        is just not worth it).

        What is useful are:

        A. A very brief overview (primarily, diagrams).
        B. Automated tests, both unit and functional (because their truth can be
        verified).
        C. User documentation (because, unlike technical documentation, I have more
        faith that if the user documentation is wrong, somebody will notice and it
        will get fixed).

        None of these appreciably increase the cost of making changes, because B and
        C are part of the natural deliverable of agile software development. So,
        these are sustainable forms of documentation.

        SteveG

        On Mon, May 30, 2011 at 4:53 AM, Gustavo Cebrian Garcia <
        g.cebrian.garcia@...> wrote:

        >
        >
        > .... to pick up the code in a short time?
        >
        > Hello,
        >
        > I am just thinking how much documentation is needed for code in these two
        > scenarios:
        >
        > -colective ownership of code
        > -No colective ownership.
        >
        > Do you get my idea? In a scenario where just a programmer is working on a
        > project, how much documentation is needed in case
        > that programmer is going to leave in a few months?
        >
        > And, if we have a team with colective ownership, it is necessary to
        > document
        > the code?
        >
        > Any articles on this? Thanks.
        >
        > Gustavo.
        >
        >


        [Non-text portions of this message have been removed]
      • Chet Hendrickson
        Hello Gustavo, That is an interesting question. Collective ownership does increase the team s overall knowledge of the code. However, not anywhere near as
        Message 3 of 4 , May 30, 2011
        • 0 Attachment
          Hello Gustavo,

          That is an interesting question. Collective ownership does increase the team's overall knowledge of the code. However, not anywhere near as much as pair programming.

          The team should agree on the appropriate level of documentation and the practices necessary to maintain it at that level. They should also monitor the effort it requires.

          From the pure XP point of view, any code that needs inline comments to be understood is not done. Our goal is to make all our design ideas explicit in the code.

          Returning to collective code ownership. Its job is to reduce queues and wait states. You have certainly hit the nail on the head that collective code ownership can only be effectively implemented what the code is sufficiently understandable that any team member can safely modify it.

          chet


          Monday, May 30, 2011, 7:53:24 AM, you wrote:



          .... to pick up the code in a short time?

          Hello,

          I am just thinking how much documentation is needed for code in these two
          scenarios:

          -colective ownership of code
          -No colective ownership.

          Do you get my idea? In a scenario where just a programmer is working on a
          project, how much documentation is needed in case
          that programmer is going to leave in a few months?

          And, if we have a team with colective ownership, it is necessary to document
          the code?

          Any articles on this? Thanks.

          Gustavo.

          [Non-text portions of this message have been removed]






          --
          Best regards,
          Chet Hendrickson mailto:lists@...
          Check out our upcoming CSM Plus courses @
          http://hendricksonxp.com/index.php?option=com_eventlist&Itemid=28

          [Non-text portions of this message have been removed]
        Your message has been successfully submitted and would be delivered to recipients shortly.