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

Re: [agileDatabases] Documentation on data projects

Expand Messages
  • Adrian Walker
    Hi Adrian, Andrew & All -- One approach to solving the problem of unsatisfactory documentation is to make the documentation executable. Then the
    Message 1 of 16 , Apr 30 2:41 PM
    • 0 Attachment
      Hi Adrian, Andrew & All --

      One approach to solving the problem of unsatisfactory documentation is to
      make the documentation executable. Then the documentation *is* the code,
      and so the two cannot get out of step.

      In case this sounds like blue sky, please see


      www.reengineeringllc.com/A_Wiki_for_Business_Rules_in_Open_Vocabulary_Executable_English.pdf

      and the system that is live online at the same site. The system
      automatically generates and runs SQL that would be too complicated to write
      reliably by hand, and it can explain the results, in English, at the
      business level. Shared use of the system is free.

      Apologies if you have seen this before, and thanks for comments.

      -- Adrian Walker

      Internet Business Logic
      A Wiki and SOA Endpoint for Executable Open Vocabulary English over SQL
      Online at www.reengineeringllc.com Shared use is free



      On Sun, Apr 27, 2008 at 10:01 PM, Andrew Gregovich <
      andrew_gregovich@...> wrote:

      > The main problem that I encounter with documentation is that it's often
      > little more than diagrams and lists which can be produced by good reverse
      > engineering tools. Even worse, documentation usually doesn't get updated as
      > often as it should be, so after a while it lags behind the real world.
      >
      > However, I have no doubt that good documentation is crucial for long term
      > maintenance of software projects whose complexity is high or where there is
      > a high staff turnaround. Its main aim should be to capture the thinking
      > process and to document considered alternatives, i.e. why particular
      > decisions have been made. As a developer, when you take on an unfamiliar
      > mound of code, you will surely see very odd looking lines - the question
      > should immediately raise: is there a good reason for them. In most cases,
      > the cause was a developer churning out code at 3am two days before the due
      > date, but often there are valid, yet obscure, arguments behind the scenes.
      > If you don't have a clear picture, you cannot make a confident judgment when
      > you need to fix a bug, refactor a module, insert new requirements etc.
      >
      > The same can be said about requirements, in the long run one faces similar
      > problems with scarce documentation, particularly if you're in a product
      > development company (you have multiple clients using the same product). You
      > often wonder about the rationale for some very funny logic, and unless you
      > have a veteran domain expert handy, you'll have no option but to keep the
      > requirements as they are, while in fact, this was just someone's "great
      > idea" which never made much sense. If you don't see the rationale behind
      > certain decisions, they are very hard to challenge.
      >
      > Documentation doesn't necessarily need to be in formal MS Word documents
      > with pretty headers and footers, informal means can be as useful. Archived
      > discussions on requriements/design in the form of e-mails or discussion
      > forums can all be of great value. You can choose to be frugal about
      > investing spending time on docs, but at the same time you need to be aware
      > how much it helps in the long term.
      >
      > Andrew
      >
      > ----- Original Message ----
      > From: Adrian Mowat <mowat27@... <mowat27%40googlemail.com>>
      > To: agileDatabases@yahoogroups.com <agileDatabases%40yahoogroups.com>;
      > agile-datamgmt@yahoogroups.com <agile-datamgmt%40yahoogroups.com>
      > Sent: Sunday, April 27, 2008 10:42:53 PM
      > Subject: [agileDatabases] Documentation on data projects
      >
      > Hi All,
      >
      > My latest blog post introduces some ideas that people who are new to Agile
      > might wish to consider about the thorny issue of documentation, or the
      > lack
      > thereof.
      >
      > http://adrianmowat. blogspot. com/2008/ 04/its-much- more-than- throwing-
      > out.html
      >
      > As ever, I am very keen for your thoughts and comments.
      >
      > Many Thanks
      >
      > Adrian
      >
      > [Non-text portions of this message have been removed]
      >
      > __________________________________________________________
      > Be a better friend, newshound, and
      > know-it-all with Yahoo! Mobile. Try it now.
      > http://mobile.yahoo.com/;_ylt=Ahu06i62sR8HDtDypao8Wcj9tAcJ
      >
      > [Non-text portions of this message have been removed]
      >
      >
      >


      [Non-text portions of this message have been removed]
    • Andrew Gregovich
      This is what I said before - if you can reverse engineer a document, then it s completely superfluous to maintain it manually. The catch is, no source code,
      Message 2 of 16 , Apr 30 7:43 PM
      • 0 Attachment
        This is what I said before - if you can reverse engineer a document, then it's completely superfluous to maintain it manually.

        The catch is, no source code, test case suite or tool can tell you intentions and rationales of the person who created the code in the first place and for long term applications. You have to then rely on tacit knowledge which may or may not be available, and often you can only make an educated guess (and strictly speaking guessing is the opposite of engineering).

        By the way, I failed to mention one of the best means of documentation - comments! If everyone adhered to a 30/70 comments/code ratio one would only need to document high level concepts and diagrams.

        Adrew


        ----- Original Message ----
        From: Adrian Walker <adriandwalker@...>
        To: agileDatabases@yahoogroups.com
        Sent: Thursday, May 1, 2008 5:41:48 AM
        Subject: Re: [agileDatabases] Documentation on data projects


        Hi Adrian, Andrew & All --

        One approach to solving the problem of unsatisfactory documentation is to
        make the documentation executable. Then the documentation *is* the code,
        and so the two cannot get out of step.

        In case this sounds like blue sky, please see

        www.reengineeringll c.com/A_Wiki_ for_Business_ Rules_in_ Open_Vocabulary_ Executable_ English.pdf

        and the system that is live online at the same site. The system
        automatically generates and runs SQL that would be too complicated to write
        reliably by hand, and it can explain the results, in English, at the
        business level. Shared use of the system is free.

        Apologies if you have seen this before, and thanks for comments.

        -- Adrian Walker

        Internet Business Logic
        A Wiki and SOA Endpoint for Executable Open Vocabulary English over SQL
        Online at www.reengineeringll c.com Shared use is free

        On Sun, Apr 27, 2008 at 10:01 PM, Andrew Gregovich <
        andrew_gregovich@ yahoo.com> wrote:

        > The main problem that I encounter with documentation is that it's often
        > little more than diagrams and lists which can be produced by good reverse
        > engineering tools. Even worse, documentation usually doesn't get updated as
        > often as it should be, so after a while it lags behind the real world.
        >
        > However, I have no doubt that good documentation is crucial for long term
        > maintenance of software projects whose complexity is high or where there is
        > a high staff turnaround. Its main aim should be to capture the thinking
        > process and to document considered alternatives, i.e. why particular
        > decisions have been made. As a developer, when you take on an unfamiliar
        > mound of code, you will surely see very odd looking lines - the question
        > should immediately raise: is there a good reason for them. In most cases,
        > the cause was a developer churning out code at 3am two days before the due
        > date, but often there are valid, yet obscure, arguments behind the scenes.
        > If you don't have a clear picture, you cannot make a confident judgment when
        > you need to fix a bug, refactor a module, insert new requirements etc.
        >
        > The same can be said about requirements, in the long run one faces similar
        > problems with scarce documentation, particularly if you're in a product
        > development company (you have multiple clients using the same product). You
        > often wonder about the rationale for some very funny logic, and unless you
        > have a veteran domain expert handy, you'll have no option but to keep the
        > requirements as they are, while in fact, this was just someone's "great
        > idea" which never made much sense. If you don't see the rationale behind
        > certain decisions, they are very hard to challenge.
        >
        > Documentation doesn't necessarily need to be in formal MS Word documents
        > with pretty headers and footers, informal means can be as useful. Archived
        > discussions on requriements/ design in the form of e-mails or discussion
        > forums can all be of great value. You can choose to be frugal about
        > investing spending time on docs, but at the same time you need to be aware
        > how much it helps in the long term.
        >
        > Andrew
        >
        > ----- Original Message ----
        > From: Adrian Mowat <mowat27@googlemail. com <mowat27%40googlema il.com>>
        > To: agileDatabases@ yahoogroups. com <agileDatabases% 40yahoogroups. com>;
        > agile-datamgmt@ yahoogroups. com <agile-datamgmt% 40yahoogroups. com>
        > Sent: Sunday, April 27, 2008 10:42:53 PM
        > Subject: [agileDatabases] Documentation on data projects
        >
        > Hi All,
        >
        > My latest blog post introduces some ideas that people who are new to Agile
        > might wish to consider about the thorny issue of documentation, or the
        > lack
        > thereof.
        >
        > http://adrianmowat. blogspot. com/2008/ 04/its-much- more-than- throwing-
        > out.html
        >
        > As ever, I am very keen for your thoughts and comments.
        >
        > Many Thanks
        >
        > Adrian
        >
        > [Non-text portions of this message have been removed]
        >
        > ____________ _________ _________ _________ _________ _________ _
        > Be a better friend, newshound, and
        > know-it-all with Yahoo! Mobile. Try it now.
        > http://mobile. yahoo.com/ ;_ylt=Ahu06i62sR 8HDtDypao8Wcj9tA cJ
        >
        > [Non-text portions of this message have been removed]
        >
        >
        >

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




        ____________________________________________________________________________________
        Be a better friend, newshound, and
        know-it-all with Yahoo! Mobile. Try it now. http://mobile.yahoo.com/;_ylt=Ahu06i62sR8HDtDypao8Wcj9tAcJ

        [Non-text portions of this message have been removed]
      • Scott Ambler
        ... Static docs (e.g. Word docs, models that don t support full engineering) will get out of sync with the code, if they were ever in sync to begin with.
        Message 3 of 16 , May 1, 2008
        • 0 Attachment
          > andrew_gregovich@...> wrote:
          >
          > > The main problem that I encounter with documentation
          > is that it's often
          > > little more than diagrams and lists which can be
          > produced by good reverse
          > > engineering tools. Even worse, documentation usually
          > doesn't get updated as
          > > often as it should be, so after a while it lags behind
          > the real world.

          Static docs (e.g. Word docs, models that don't support full engineering) will get out of sync with the code, if they were ever in sync to begin with. That's why many agilists prefer executable docs in the form of tests. See http://www.agiledata.org/essays/tdd.html

          > >
          > > However, I have no doubt that good documentation is
          > crucial for long term
          > > maintenance of software projects whose complexity is
          > high or where there is
          > > a high staff turnaround. Its main aim should be to
          > capture the thinking
          > > process and to document considered alternatives, i.e.
          > why particular
          > > decisions have been made.

          I think that's a huge assumption. I've heard this claim for years, yet in practice at best it's interesting to know why someone did something but it really doesn't affect my decision making at all.

          > As a developer, when you
          > take on an unfamiliar
          > > mound of code, you will surely see very odd looking
          > lines - the question
          > > should immediately raise: is there a good reason for
          > them. In most cases,
          > > the cause was a developer churning out code at 3am two
          > days before the due
          > > date, but often there are valid, yet obscure,
          > arguments behind the scenes.

          So what? The real question TODAY is whether that code implements logic that is applicable now. It may have been applicable when it was first written, let's give people the benefit of the doubt, but requirements may have changed since then. When I see esoteric code in a spot where I need to do an update to implement new functionality, I refactor it so that it isn't esoteric. Once it's of high quality, then I change it as needed to support the new/changed functionality that I'm currently focused on.


          > > If you don't have a clear picture, you cannot make
          > a confident judgment when
          > > you need to fix a bug, refactor a module, insert new
          > requirements etc.

          Sure you can. Assume that it's the right thing to do. Refactor it if needed. Refactoring doesn't change the behavior, it merely improves the quality. So it's safe to do. If you're worried that the new requirements contradict the existing functionality, ask your stakeholders about it (e.g. do some business analysis oriented model storming)

          > >
          > > Documentation doesn't necessarily need to be in
          > formal MS Word documents
          > > with pretty headers and footers, informal means can be
          > as useful. Archived
          > > discussions on requriements/design in the form of
          > e-mails or discussion
          > > forums can all be of great value. You can choose to be
          > frugal about
          > > investing spending time on docs, but at the same time
          > you need to be aware
          > > how much it helps in the long term.

          You might want to check out the beta for Rational Team Concert at www.jazz.net. It treats work items (requirements & defects) and any online chat that you have with others as first class artifacts. End result is that your chat is automatically archived and associated with the work items, which in turn is associated with your code. So you could find the original thinking if you wanted, assuming that it was captured in chat or in the original work item description.

          - Scott


          __________________________________________________________________
          Ask a question on any topic and get answers from real people. Go to Yahoo! Answers and share what you know at http://ca.answers.yahoo.com
        • Willem Bogaerts
          ... Yikes! Comments CAN be useful, but only as a last resort. Many things are better comments than language comments themselves. Especially identifiers.
          Message 4 of 16 , May 1, 2008
          • 0 Attachment
            > By the way, I failed to mention one of the best means of documentation - comments!
            > If everyone adhered to a 30/70 comments/code ratio one would only need to document
            > high level concepts and diagrams.


            Yikes! Comments CAN be useful, but only as a last resort. Many things
            are better comments than language comments themselves. Especially
            identifiers. Compare:

            -- @Param @i: Zero based index that denotes which Item you want to get.
            CREATE PROCEDURE Item(@i AS INTEGER)
            ...

            to:

            CREATE PROCEDURE Item(@ZeroBasedIndex AS INTEGER)
            ...

            In the last case, any IDE or editor with autocompletion will show the
            documentation where it is *used*, as opposed to where it is *defined*.
            Definitions are just the least useful places to put the documentation
            in, unless you actually have to look at it.

            What's more, comments are not part of the language itself. They are not
            compiled and therefore not checked by the compiler. I have seen far too
            many comments that were copy-pasted along with the functions and then
            only the functions were adapted. Comments are just text and therefore
            not better than separate documents. They *should* be kept up-to-date,
            but nothing will enforce it and therefore nobody does.

            For the same reason, in my opinion, every decent database frontend
            should show column comments and table comments if there are any. Too bad
            so little of them do!

            Best regards,
            Willem Bogaerts
          • Curt Sampson
            ... I disagree. If you ve got very high staff turnaround, you re going to hurt the project, and there s not much you can do about. There s always a lot of
            Message 5 of 16 , May 5, 2008
            • 0 Attachment
              On 2008-04-27 19:01 -0700 (Sun), Andrew Gregovich wrote:

              > However, I have no doubt that good documentation is crucial for long
              > term maintenance of software projects whose complexity is high or
              > where there is a high staff turnaround.

              I disagree. If you've got very high staff turnaround, you're going to
              hurt the project, and there's not much you can do about. There's always
              a lot of knowledge internal to the people with experience that can't
              be brought out in documentation. (If it could, there'd be too much to
              index, much less read.)

              For project handovers, I've heard the argument that one needs good docs.
              On the other hand, for almost any handover, I'd argue that I can do it
              at half the cost by avoiding a sharp cutover and instead transitioning
              people in and out gradually, in groups of no more than half the team
              size.

              So often documentation needs only exist because someone added another,
              unnecessary requirement that has little or no real justifcation and,
              when relaxed, saves you a lot of time and money.

              On 2008-04-30 19:43 -0700 (Wed), Andrew Gregovich wrote:

              > The catch is, no source code, test case suite or tool can tell you
              > intentions and rationales of the person who created the code in the
              > first place....

              Unless the coder is any good at communicating through the code.

              There's an anecdote from one of the AW Kent Beck Signature series books
              where someone comes in to interview for the CCC project (Ron Jeffries,
              perhaps?), reads some of the code, and is stunned to discover that it
              reads as well as an English description of what the code is supposed to
              be doing. If anybody could get me a copy of this anecdote (it's less
              than a page), or at least tell me what the source is, I'd appreciate it.

              > By the way, I failed to mention one of the best means of documentation
              > - comments!

              No way, comments are horrible. A comment is an admission that you can't
              write the code clearly enough to communicate what it does, and comments
              degrade as they age, sometimes badly enough to very seriously mislead
              people.

              cjs
              --
              Curt Sampson <cjs@...> +81 90 7737 2974
              Mobile sites and software consulting: http://www.starling-software.com
            • Todd Carrico
              ... documentation ... No way, comments are horrible. A comment is an admission that you can t write the code clearly enough to communicate what it does, and
              Message 6 of 16 , May 5, 2008
              • 0 Attachment
                > > By the way, I failed to mention one of the best means of
                documentation
                > - comments!

                No way, comments are horrible. A comment is an admission that you can't
                write the code clearly enough to communicate what it does, and comments
                degrade as they age, sometimes badly enough to very seriously mislead
                people.

                cjs
                --



                Comments can give you insight into why the engineer did what they did.
                Code can tell you what they did for sure, but why they did something is
                another story.

                Comments should be treated and maintained like the code, and they should
                be part of any review if one is taken. They should also focus on the
                things that the code can't tell you. In short, there should be very
                little commenting, but the statement that comments are horrible is too
                broad. Horrible comments are horrible.

                tc



                [Non-text portions of this message have been removed]
              • John Roth
                How versus why keeps coming up whenever people bring up comments. Quite frankly, I d like to see some examples of code that is supposed to need comments, and
                Message 7 of 16 , May 5, 2008
                • 0 Attachment
                  How versus why keeps coming up whenever people
                  bring up comments. Quite frankly, I'd like to see some
                  examples of code that is supposed to need comments,
                  and then take it apart to see how it could be written
                  to be more intention revealing.

                  Remember that "intention revealing" is the third of
                  four elements in Simple Design. I have this suspicion that
                  many of the places people feel the need for comments
                  are actually process smells. It would be interesting to
                  see a case where comments really were needed that
                  wasn't due to poor process, language, tools or whatever.

                  John Roth


                  ----- Original Message -----
                  From: "Todd Carrico" <todd.carrico@...>
                  To: <agileDatabases@yahoogroups.com>
                  Sent: Monday, May 05, 2008 8:44 AM
                  Subject: RE: [agileDatabases] Documentation on data projects


                  >> > By the way, I failed to mention one of the best means of
                  > documentation
                  >> - comments!
                  >
                  > No way, comments are horrible. A comment is an admission that you can't
                  > write the code clearly enough to communicate what it does, and comments
                  > degrade as they age, sometimes badly enough to very seriously mislead
                  > people.
                  >
                  > cjs
                  > --
                  >
                  >
                  >
                  > Comments can give you insight into why the engineer did what they did.
                  > Code can tell you what they did for sure, but why they did something is
                  > another story.
                  >
                  > Comments should be treated and maintained like the code, and they should
                  > be part of any review if one is taken. They should also focus on the
                  > things that the code can't tell you. In short, there should be very
                  > little commenting, but the statement that comments are horrible is too
                  > broad. Horrible comments are horrible.
                  >
                  > tc
                  >
                  >
                  >
                  > [Non-text portions of this message have been removed]
                  >
                  >
                • Adrian Mowat
                  Hi All, If you are writing in a 3GL like Java or C#, then I agree that clear code trumps comments. My original post was with regard to data projects like data
                  Message 8 of 16 , May 5, 2008
                  • 0 Attachment
                    Hi All,

                    If you are writing in a 3GL like Java or C#, then I agree that clear code
                    trumps comments.

                    My original post was with regard to data projects like data warehouses where
                    we use 4th generation ETL tools which are programmed via a graphical
                    interface. In this case, clear component naming takes the same place. Some
                    people like to use comments to indicate data volumes on files but I
                    personally feel a metadata environment should be used instead.

                    Adrian

                    2008/5/5 John Roth <JohnRoth1@...>:

                    > How versus why keeps coming up whenever people
                    > bring up comments. Quite frankly, I'd like to see some
                    > examples of code that is supposed to need comments,
                    > and then take it apart to see how it could be written
                    > to be more intention revealing.
                    >
                    > Remember that "intention revealing" is the third of
                    > four elements in Simple Design. I have this suspicion that
                    > many of the places people feel the need for comments
                    > are actually process smells. It would be interesting to
                    > see a case where comments really were needed that
                    > wasn't due to poor process, language, tools or whatever.
                    >
                    > John Roth
                    >
                    > ----- Original Message -----
                    > From: "Todd Carrico" <todd.carrico@... <todd.carrico%40match.com>>
                    > To: <agileDatabases@yahoogroups.com <agileDatabases%40yahoogroups.com>>
                    > Sent: Monday, May 05, 2008 8:44 AM
                    > Subject: RE: [agileDatabases] Documentation on data projects
                    >
                    > >> > By the way, I failed to mention one of the best means of
                    > > documentation
                    > >> - comments!
                    > >
                    > > No way, comments are horrible. A comment is an admission that you can't
                    > > write the code clearly enough to communicate what it does, and comments
                    > > degrade as they age, sometimes badly enough to very seriously mislead
                    > > people.
                    > >
                    > > cjs
                    > > --
                    > >
                    > >
                    > >
                    > > Comments can give you insight into why the engineer did what they did.
                    > > Code can tell you what they did for sure, but why they did something is
                    > > another story.
                    > >
                    > > Comments should be treated and maintained like the code, and they should
                    > > be part of any review if one is taken. They should also focus on the
                    > > things that the code can't tell you. In short, there should be very
                    > > little commenting, but the statement that comments are horrible is too
                    > > broad. Horrible comments are horrible.
                    > >
                    > > tc
                    > >
                    > >
                    > >
                    > > [Non-text portions of this message have been removed]
                    > >
                    > >
                    >
                    >
                    >


                    [Non-text portions of this message have been removed]
                  • cstrong@arielpartners.com
                    //printableAttributes.add(new SimpleProperty( tourChangeReason , overrideEvent.getTourChangeReason())); //printableAttributes.add(new
                    Message 9 of 16 , May 5, 2008
                    • 0 Attachment
                      //printableAttributes.add(new SimpleProperty("tourChangeReason",
                      overrideEvent.getTourChangeReason()));
                      //printableAttributes.add(new SimpleProperty("shiftOverrideTypeId",
                      overrideEvent.getShiftOverrideType().getId()));
                      //
                      // For DR 5.1 we are employing a kind of optimization for the GUI where
                      the GUI assumes that any time we send
                      // a textual string the type can only be OVERRIDE_TYPE_NORMAL, so it is
                      assumed to be so, and so the GUI
                      // can get away with using only one field for both.
                      //
                      // Basically the logic is saying the following: "If the user went to the
                      time and trouble of actually
                      // typing a textual reason for the shift override, always give preference
                      to that and display
                      // only that. If not, go ahead and display the dropdown of the pre-canned
                      shift override reasons.
                      //
                      String blendedShiftOverrideType = overrideEvent.getTourChangeReason();
                      if ((null == blendedShiftOverrideType) ||
                      (blendedShiftOverrideType.equals(""))) {
                      blendedShiftOverrideType = ""+overrideEvent.getShiftOverrideType().getId();
                      }
                      printableAttributes.add(new SimpleProperty("shiftOverrideTypeId",
                      blendedShiftOverrideType));

                      I can come up with many more such examples. Work on a large scale
                      enterprise software project (e.g. 500k -> more than 1M SLOC, >3 dozen
                      developers, and more than 100K user base, over a period of several years
                      (with normal staff turnover) and then see if you still feel the same way.
                      :-)

                      --Craeg

                      > How versus why keeps coming up whenever people
                      > bring up comments. Quite frankly, I'd like to see some
                      > examples of code that is supposed to need comments,
                      > and then take it apart to see how it could be written
                      > to be more intention revealing.
                      >
                      > Remember that "intention revealing" is the third of
                      > four elements in Simple Design. I have this suspicion that
                      > many of the places people feel the need for comments
                      > are actually process smells. It would be interesting to
                      > see a case where comments really were needed that
                      > wasn't due to poor process, language, tools or whatever.
                      >
                      > John Roth
                      >
                      >
                      > ----- Original Message -----
                      > From: "Todd Carrico" <todd.carrico@...>
                      > To: <agileDatabases@yahoogroups.com>
                      > Sent: Monday, May 05, 2008 8:44 AM
                      > Subject: RE: [agileDatabases] Documentation on data projects
                      >
                      >
                      >>> > By the way, I failed to mention one of the best means of
                      >> documentation
                      >>> - comments!
                      >>
                      >> No way, comments are horrible. A comment is an admission that you can't
                      >> write the code clearly enough to communicate what it does, and comments
                      >> degrade as they age, sometimes badly enough to very seriously mislead
                      >> people.
                      >>
                      >> cjs
                      >> --
                      >>
                      >>
                      >>
                      >> Comments can give you insight into why the engineer did what they did.
                      >> Code can tell you what they did for sure, but why they did something is
                      >> another story.
                      >>
                      >> Comments should be treated and maintained like the code, and they should
                      >> be part of any review if one is taken. They should also focus on the
                      >> things that the code can't tell you. In short, there should be very
                      >> little commenting, but the statement that comments are horrible is too
                      >> broad. Horrible comments are horrible.
                      >>
                      >> tc
                      >>
                      >>
                      >>
                      >> [Non-text portions of this message have been removed]
                      >>
                      >>
                      >
                    • cstrong@arielpartners.com
                      Let me see if I can summarize my position in English. Code comments can provide essential guidance to the reader about the reasons behind the design of a
                      Message 10 of 16 , May 5, 2008
                      • 0 Attachment
                        Let me see if I can summarize my position in English.

                        Code comments can provide essential guidance to the reader
                        about the reasons behind the design of a particular piece of code
                        when the design is informed by constraints or requirements
                        of other software components that are discontiguous in processing time
                        and/or space,
                        espcially in the case where the design is in a high degree of flux due to
                        size, complexity, or criticality of a software project,
                        where refactoring said design to the point where it reaches the level of
                        fully "intention-revealing" code would likely amount to over-engineering
                        (i.e. violating YAGNI).

                        -Or-

                        Code comments are a shortcut to be used when the cost vs benefit of better
                        solutions are not justified.

                        Flame away ;)


                        --Craeg


                        > //printableAttributes.add(new SimpleProperty("tourChangeReason",
                        > overrideEvent.getTourChangeReason()));
                        > //printableAttributes.add(new SimpleProperty("shiftOverrideTypeId",
                        > overrideEvent.getShiftOverrideType().getId()));
                        > //
                        > // For DR 5.1 we are employing a kind of optimization for the GUI where
                        > the GUI assumes that any time we send
                        > // a textual string the type can only be OVERRIDE_TYPE_NORMAL, so it is
                        > assumed to be so, and so the GUI
                        > // can get away with using only one field for both.
                        > //
                        > // Basically the logic is saying the following: "If the user went to the
                        > time and trouble of actually
                        > // typing a textual reason for the shift override, always give preference
                        > to that and display
                        > // only that. If not, go ahead and display the dropdown of the pre-canned
                        > shift override reasons.
                        > //
                        > String blendedShiftOverrideType = overrideEvent.getTourChangeReason();
                        > if ((null == blendedShiftOverrideType) ||
                        > (blendedShiftOverrideType.equals(""))) {
                        > blendedShiftOverrideType =
                        > ""+overrideEvent.getShiftOverrideType().getId();
                        > }
                        > printableAttributes.add(new SimpleProperty("shiftOverrideTypeId",
                        > blendedShiftOverrideType));
                        >
                        > I can come up with many more such examples. Work on a large scale
                        > enterprise software project (e.g. 500k -> more than 1M SLOC, >3 dozen
                        > developers, and more than 100K user base, over a period of several years
                        > (with normal staff turnover) and then see if you still feel the same way.
                        > :-)
                        >
                        > --Craeg
                        >
                        >> How versus why keeps coming up whenever people
                        >> bring up comments. Quite frankly, I'd like to see some
                        >> examples of code that is supposed to need comments,
                        >> and then take it apart to see how it could be written
                        >> to be more intention revealing.
                        >>
                        >> Remember that "intention revealing" is the third of
                        >> four elements in Simple Design. I have this suspicion that
                        >> many of the places people feel the need for comments
                        >> are actually process smells. It would be interesting to
                        >> see a case where comments really were needed that
                        >> wasn't due to poor process, language, tools or whatever.
                        >>
                        >> John Roth
                        >>
                        >>
                        >> ----- Original Message -----
                        >> From: "Todd Carrico" <todd.carrico@...>
                        >> To: <agileDatabases@yahoogroups.com>
                        >> Sent: Monday, May 05, 2008 8:44 AM
                        >> Subject: RE: [agileDatabases] Documentation on data projects
                        >>
                        >>
                        >>>> > By the way, I failed to mention one of the best means of
                        >>> documentation
                        >>>> - comments!
                        >>>
                        >>> No way, comments are horrible. A comment is an admission that you can't
                        >>> write the code clearly enough to communicate what it does, and comments
                        >>> degrade as they age, sometimes badly enough to very seriously mislead
                        >>> people.
                        >>>
                        >>> cjs
                        >>> --
                        >>>
                        >>>
                        >>>
                        >>> Comments can give you insight into why the engineer did what they did.
                        >>> Code can tell you what they did for sure, but why they did something is
                        >>> another story.
                        >>>
                        >>> Comments should be treated and maintained like the code, and they
                        >>> should
                        >>> be part of any review if one is taken. They should also focus on the
                        >>> things that the code can't tell you. In short, there should be very
                        >>> little commenting, but the statement that comments are horrible is too
                        >>> broad. Horrible comments are horrible.
                        >>>
                        >>> tc
                        >>>
                        >>>
                        >>>
                        >>> [Non-text portions of this message have been removed]
                        >>>
                        >>>
                        >>
                        >
                        >
                      • John Roth
                        As I read the code, I see two things going on. One is (possibly) unclear code. A really strict OO approach would wrap the concept of (string if present, else
                        Message 11 of 16 , May 5, 2008
                        • 0 Attachment
                          As I read the code, I see two things going on.
                          One is (possibly) unclear code. A really strict
                          OO approach would wrap the concept of
                          (string if present, else selection) in an object,
                          and would probably make a composite widget
                          to display it. That makes the --design-- very, very
                          clear.

                          The second issue is to document why it's done
                          that way. I normally don't think that has to be
                          done in the code; that's the function of automated
                          acceptance tests.

                          John Roth




                          ----- Original Message -----
                          From: <cstrong@...>
                          To: <agileDatabases@yahoogroups.com>
                          Cc: <agiledatabases@yahoogroups.com>
                          Sent: Monday, May 05, 2008 3:14 PM
                          Subject: Re: [agileDatabases] Documentation on data projects


                          > //printableAttributes.add(new SimpleProperty("tourChangeReason",
                          > overrideEvent.getTourChangeReason()));
                          > //printableAttributes.add(new SimpleProperty("shiftOverrideTypeId",
                          > overrideEvent.getShiftOverrideType().getId()));
                          > //
                          > // For DR 5.1 we are employing a kind of optimization for the GUI where
                          > the GUI assumes that any time we send
                          > // a textual string the type can only be OVERRIDE_TYPE_NORMAL, so it is
                          > assumed to be so, and so the GUI
                          > // can get away with using only one field for both.
                          > //
                          > // Basically the logic is saying the following: "If the user went to the
                          > time and trouble of actually
                          > // typing a textual reason for the shift override, always give preference
                          > to that and display
                          > // only that. If not, go ahead and display the dropdown of the pre-canned
                          > shift override reasons.
                          > //
                          > String blendedShiftOverrideType = overrideEvent.getTourChangeReason();
                          > if ((null == blendedShiftOverrideType) ||
                          > (blendedShiftOverrideType.equals(""))) {
                          > blendedShiftOverrideType =
                          > ""+overrideEvent.getShiftOverrideType().getId();
                          > }
                          > printableAttributes.add(new SimpleProperty("shiftOverrideTypeId",
                          > blendedShiftOverrideType));
                          >
                          > I can come up with many more such examples. Work on a large scale
                          > enterprise software project (e.g. 500k -> more than 1M SLOC, >3 dozen
                          > developers, and more than 100K user base, over a period of several years
                          > (with normal staff turnover) and then see if you still feel the same way.
                          > :-)
                          >
                          > --Craeg
                          >
                          >> How versus why keeps coming up whenever people
                          >> bring up comments. Quite frankly, I'd like to see some
                          >> examples of code that is supposed to need comments,
                          >> and then take it apart to see how it could be written
                          >> to be more intention revealing.
                          >>
                          >> Remember that "intention revealing" is the third of
                          >> four elements in Simple Design. I have this suspicion that
                          >> many of the places people feel the need for comments
                          >> are actually process smells. It would be interesting to
                          >> see a case where comments really were needed that
                          >> wasn't due to poor process, language, tools or whatever.
                          >>
                          >> John Roth
                          >>
                          >>
                          >> ----- Original Message -----
                          >> From: "Todd Carrico" <todd.carrico@...>
                          >> To: <agileDatabases@yahoogroups.com>
                          >> Sent: Monday, May 05, 2008 8:44 AM
                          >> Subject: RE: [agileDatabases] Documentation on data projects
                          >>
                          >>
                          >>>> > By the way, I failed to mention one of the best means of
                          >>> documentation
                          >>>> - comments!
                          >>>
                          >>> No way, comments are horrible. A comment is an admission that you can't
                          >>> write the code clearly enough to communicate what it does, and comments
                          >>> degrade as they age, sometimes badly enough to very seriously mislead
                          >>> people.
                          >>>
                          >>> cjs
                          >>> --
                          >>>
                          >>>
                          >>>
                          >>> Comments can give you insight into why the engineer did what they did.
                          >>> Code can tell you what they did for sure, but why they did something is
                          >>> another story.
                          >>>
                          >>> Comments should be treated and maintained like the code, and they should
                          >>> be part of any review if one is taken. They should also focus on the
                          >>> things that the code can't tell you. In short, there should be very
                          >>> little commenting, but the statement that comments are horrible is too
                          >>> broad. Horrible comments are horrible.
                          >>>
                          >>> tc
                          >>>
                          >>>
                          >>>
                          >>> [Non-text portions of this message have been removed]
                          >>>
                          >>>
                          >>
                          >
                          >
                        • Curt Sampson
                          ... ...all sorts of good things, yes. Perhaps we can summarize the issue in a different way: 1. Code comments do not contribute to the code itself; anything
                          Message 12 of 16 , May 5, 2008
                          • 0 Attachment
                            On 2008-05-05 17:30 -0400 (Mon), cstrong@... wrote:

                            > Code comments can provide...

                            ...all sorts of good things, yes. Perhaps we can summarize the issue in
                            a different way:

                            1. Code comments do not contribute to the code itself; anything said in
                            a comment about what code does do is going to be repeated in the code
                            itself.

                            2. Code comments aren't testable, and don't test anything. Thus, they
                            open developers up to error on two fronts: the comment may become wrong,
                            and you have to rely on people to catch that, and the code the comment
                            is telling you about may become wrong, and that can be caught only by
                            people who read the comment and manually check the code.

                            So basically, comments require more manual work and are more error
                            prone.

                            > Code comments are a shortcut to be used when the cost vs benefit of better
                            > solutions are not justified.

                            Sure. I use comments from time to time; one should always be looking
                            at the cost-benefit trade-offs of anything. But comments are far more
                            expensive than most people think. Certainly they should never be a
                            preferred method of specifying what your system should do.

                            On 2008-05-05 19:41 +0100 (Mon), Adrian Mowat wrote:

                            > If you are writing in a 3GL like Java or C#, then I agree that clear code
                            > trumps comments.
                            >
                            > My original post was with regard to data projects like data warehouses where
                            > we use 4th generation ETL tools which are programmed via a graphical
                            > interface. In this case, clear component naming takes the same place.

                            Actually, in any language, "rename method to replace comment" is a
                            standard refactoring.

                            As for being stuck with tools programmed with a GUI, well, that's
                            generally something you want to get out of if you possibly can. GUIs
                            tend to be really bad platforms for things like building domain-specific
                            languages.

                            cjs
                            --
                            Curt Sampson <cjs@...> +81 90 7737 2974
                            Mobile sites and software consulting: http://www.starling-software.com
                          Your message has been successfully submitted and would be delivered to recipients shortly.