Are Comments a Waste of Time? - Page 2


DevX Home    Today's Headlines   Articles Archive   Tip Bank   Forums   

Page 2 of 2 FirstFirst 12
Results 16 to 26 of 26

Thread: Are Comments a Waste of Time?

  1. #16
    R. Joe Reich Guest

    Re: Are Comments a Waste of Time?


    I have two things to say.

    I -
    1. Every routine deserves a header
    2. Every algorithm deserves a 'heads-up'
    (note an assignment, or loop isn't ness. a algorithm)
    3. Every planned revision deserves a note.

    Basically I think the author is a snerk who's never had to come into a project
    during the last two months and ramp up on his own and completely understand
    the system within a week so he can finish the system.

    II -
    I think the image below says it all...
    (assuming this site doesn't kill the link)
    http://www.cyphersolutions.com/joe.r...nloads/tip.jpg

    > "Prashant" <pkomaragiri@hotmail.com> wrote:
    > Hi,
    > I think comments play an important role in Explaining code
    > to someone who has not written it and it hardly takes any
    > time. When i go through somethird party code, The comment
    > itself makes it easy to understand the code otherwise
    > would be quite a task to understand it.I agree that some
    > comments on like get and set methods seems useless , but
    > then it is always good to be explicitly mention it.
    >
    > Prashant
    >



  2. #17
    R. Joe Reich Guest

    Re: Are Comments a Waste of Time?


    Amen Brother Nesel, preach on.

    <grin>
    Well met all the same, right down to the satirical jab at his ad hoc remark
    about his older brother.

    Until software writes itself and I have my flying car, I'm going to live
    by the following...
    http://www.cyphersolutions.com/joe.r...nloads/tip.jpg

    R. Joe Reich


    > "Dtr. Mike Nesel" <mcnesel@pacbell.net> wrote:
    >
    > Books are a waste of time, too!
    >
    > This is so, because I don't like books. They are often so
    > useless that I usually don't read them. Ever since my older
    > brother caught me reading Green Eggs and Ham as a child and
    > then broke the news to me that it was absolute fiction,I've
    > developed a keen distrust of books. This opinion only
    > solidified when I pursued my computer science degree. I
    > realized that my classmates and I read books only to earn
    > good marks from mean-spirited instructors who were more
    > concerned with how many books we read rather than whether
    > or not we really understood them! Simply put, I felt that
    > books were a waste of time.
    >
    > Dtr. Mike Nesel, PhDSt, MDD, MsS, FS
    >
    >



  3. #18
    R. Joe Reich Guest

    Re: Are Comments a Waste of Time?


    Still sounds like an "Ad Hoc" argument to me.

    The fact that an algorithm should be self-describing is no reason to omit
    high level 'heads-up / this is what we are doing here' comments. Especially
    if you're doing something in a particularily 'nifty' method.

    While I don't think every assignment and logical branch needs a comment,
    it DOES HURT ANYTHING. Rather that than the alternative.

    > "CliffordEW" <williams@southern.edu> wrote:
    >
    > I am sharing this article with my class on "Application Programming".
    > I am one of those "mean-spririted" teachers that require too many
    > comments. His second bulleted reason for disliking comments is very
    > good. It is a mistake to write comments that tell what the code
    > does. The code itself must be written to tell the reader what the
    > code does. If it doesn't the code needs to be rewritten. Good,
    > worthwhile comments tell why the code does what it does. And
    > sometimes, they tell what the code ought to do, but doesn't yet.
    > But in that case the code should be changed. Not left wrong
    > through release after release.
    >




  4. #19
    Chris Maertz Guest

    Re: Are Comments a Waste of Time?


    I believe comments are just as important as the code. When juggling multiple
    projects (some of which you are working on jointly with others), it is extremely
    helpful to have comments that help you to orientate yourself when you are
    switching from project to project.

    HOWEVER...I believe an even larger argument can be made for proper planning
    and documentation of the project before you even open your IDE of choice.
    Without the documentation and a plan, coding and commenting is a nightmare.



    "Glen Kunene" <gkunene@devx.com> wrote:
    >How useful to you are code comments? Do you write them only out of habit

    or
    >do you believe they serve an important function?
    >
    >http://www.java-zone.com/free/articl...Kabutz06-1.asp
    >
    >Let us know.
    >
    >Glen Kunene
    >Senior Editor
    >DevX.com
    >
    >



  5. #20
    Jason Guest

    Re: Are Comments a Waste of Time?


    Comments are 100% vital to writing any kind of maintainable code. One of
    the rules I make all of my developers adhere to is writing of their comments
    before any of their code. Part of our detailed design process is to take
    the public API (All public objects and their public methods) and add the
    private methods and objects being used. After we've defined all of those
    in a Word document we then add processing instructions which are readable
    (part of the requirement is that business anlaysts, testers, and developers
    all have to be able to understand them).

    Once we have the detailed design document we build our objects and paste
    the processing instructions in as comments. These comments become the foundation
    for the code we write.

    When it comes time for the code reviews (we review code at three different
    parts of our life-cycle) the comments help us understand what the code is
    doing.

    It's even more important when noone has looked at a particular piece of code
    for over two years and someone asks us to make an enhancement on it, we can
    then read the comments quickly figure out what we need to change, and then
    modify the code.

    "Chris Maertz" <cmaertz@securitymicro.com> wrote:
    >
    >I believe comments are just as important as the code. When juggling multiple
    >projects (some of which you are working on jointly with others), it is extremely
    >helpful to have comments that help you to orientate yourself when you are
    >switching from project to project.
    >
    >HOWEVER...I believe an even larger argument can be made for proper planning
    >and documentation of the project before you even open your IDE of choice.
    >Without the documentation and a plan, coding and commenting is a nightmare.
    >
    >
    >
    >"Glen Kunene" <gkunene@devx.com> wrote:
    >>How useful to you are code comments? Do you write them only out of habit

    >or
    >>do you believe they serve an important function?
    >>
    >>http://www.java-zone.com/free/articl...Kabutz06-1.asp
    >>
    >>Let us know.
    >>
    >>Glen Kunene
    >>Senior Editor
    >>DevX.com
    >>
    >>

    >



  6. #21
    MarkN Guest

    Re: Are Comments a Waste of Time?


    100% vital? You should start using an OO language!

    In the days of procedural coding[I speak of it as though it were dead - I
    wish it was] comments were 100% vital. But with OO languages I can't see
    them being even close to 100%. Now if you don't have the source I can see
    it, but then how do you know if the comments are accurate? Only by the tight
    process you use (which I'm not saying is bad) can this happen. To verify
    the validity of the comments you have to look at the code. So if you have
    to look at the code anyway ... . If OO code needs to be commented then maybe
    it needs to be refactored instead. And your walk throughs (code reviews)
    should control this. If needed, a high level explaination at the top of
    the class should be sufficient. If the code needs a comment and refactoring
    doesn't help then add a comment.

    I'm glad you are able to do all you design up front. Not many places can.
    Some can be done, but many(most?) can't. They end up performing iterative
    design and commenting\coding and then changing both when the design changes
    or new things come to light. Sometimes the coding has to be done first so
    you see if it even will work. Current tools like XDE from Rational allow
    you to take that code and view it via UML.

    A good IDE for and OO language that assists with refactoring (i.e. WSAD),
    'reverse engineering' (i.e. XDE), unit testing (i.e. JUnit) and that versions
    down to the method (i.e. WSDE) is probably more useful and important than
    comments. Combine this with Code/Design reviews to ensure good quality code
    (providing the reviewers know what it is) and you will have little need for
    them.

    While I like most of the things done in your development process (esp Code
    Reviews), it is the textbook/classical design process and in reality doesn't
    work in many places for many reasons.

    Mark

    "Jason" <ice1066@hotmail.com> wrote:
    >
    >Comments are 100% vital to writing any kind of maintainable code. One of
    >the rules I make all of my developers adhere to is writing of their comments
    >before any of their code. Part of our detailed design process is to take
    >the public API (All public objects and their public methods) and add the
    >private methods and objects being used. After we've defined all of those
    >in a Word document we then add processing instructions which are readable
    >(part of the requirement is that business anlaysts, testers, and developers
    >all have to be able to understand them).
    >
    >Once we have the detailed design document we build our objects and paste
    >the processing instructions in as comments. These comments become the foundation
    >for the code we write.
    >
    >When it comes time for the code reviews (we review code at three different
    >parts of our life-cycle) the comments help us understand what the code is
    >doing.
    >
    >It's even more important when noone has looked at a particular piece of

    code
    >for over two years and someone asks us to make an enhancement on it, we

    can
    >then read the comments quickly figure out what we need to change, and then
    >modify the code.
    >
    >"Chris Maertz" <cmaertz@securitymicro.com> wrote:
    >>
    >>I believe comments are just as important as the code. When juggling multiple
    >>projects (some of which you are working on jointly with others), it is

    extremely
    >>helpful to have comments that help you to orientate yourself when you are
    >>switching from project to project.
    >>
    >>HOWEVER...I believe an even larger argument can be made for proper planning
    >>and documentation of the project before you even open your IDE of choice.
    >>Without the documentation and a plan, coding and commenting is a nightmare.
    >>
    >>
    >>
    >>"Glen Kunene" <gkunene@devx.com> wrote:
    >>>How useful to you are code comments? Do you write them only out of habit

    >>or
    >>>do you believe they serve an important function?
    >>>
    >>>http://www.java-zone.com/free/articl...Kabutz06-1.asp
    >>>
    >>>Let us know.
    >>>
    >>>Glen Kunene
    >>>Senior Editor
    >>>DevX.com
    >>>
    >>>

    >>

    >



  7. #22
    Jason Guest

    Re: Are Comments a Waste of Time?


    I do use an OO language, it's just that I'm better at reading English. When
    searching for something, I read the English description and when I found
    what I'm looking for, I then look at the code, it's like looking for something
    in the phone book, I look for the letter Ch's and then for the Cheetah's.

    Our design process is actually an iterative process. When we start the technical
    side of a project we sit down and identify all the pieces of the puzzle,
    do we need MQ Series, Siebel, VB, J2EE, Tuxedo, etc. After that, we figure
    out what each piece needs to do. We then look at our skill set and figure
    out if we don't know how to do something. If there's something we're not
    sure of (design patterns are great), we build a prototype to test that one
    piece, and it's just enough to prove to upper management that we can implement
    the solution.

    Our testing cycle also has time built-in for code and design re-reviews.
    We also have a process which keeps everyone visible of the changes going
    on. Having the comments and the design up front, allow us to do impact analysis
    and prioritize our changes according to cost and timeline.

    During initial development usually one person is responsible for a section
    of code, however, once we hit system testing it could be anyone of 15 to
    20 developers that go in and fix the code. The comments really make it easy
    for someone to see what is going on without having to decode a semi-cryptic
    statement.

    Keeping the comments in synch isn't really a bad thing. It's actually an
    informal review process, because as you're updating the documentation you
    look at the code and you sometimes realize, what was I thinking when I coded
    this. The more times you read the code the better it becomes because you
    can fine tune it.

    I would disagree with the statement that the methodology is not based on
    the real world, since implementing this methodology we have seen a drastic
    reduction in the number of defects our code has when it hits production,
    change requests take less time, support costs are lower, developer productivity
    is way up. The methodology we use is based on best practices from a number
    of industries and has been customized for our environment. I'm not saying
    it's perfect, it's the best, or it's the only way, but I remember the days
    when we weren't using it, and I don't miss the pages at 3AM telling me another
    production defect was found. I don't miss the days of working for 36 hours
    straight because we were using the OTFP/CLH method (on-the-fly-programming/code-like-****)
    and completely botched the design.

    My team has delivered its last five projects either on-time or ahead of schedule,
    and we've been under budget each time. One release alone had 80 approved
    change requests (a couple of rogue one's made there way in as well), and
    our ability to turn them around so quickly was directly a link of our development
    process working correctly.

    Becuase of this methodology my team has become the gold star team within
    our company and we're working with other teams improve their processes.
    A methodology alone will not solve your problems (the teams we're helping
    use the same methodology and still have problems). It's how your direct
    reports, you, your leaders, and his leaders manage the process.

    I'll step down off my soapbox now.

    "MarkN" <m@n.com> wrote:
    >
    >100% vital? You should start using an OO language!
    >
    >In the days of procedural coding[I speak of it as though it were dead -

    I
    >wish it was] comments were 100% vital. But with OO languages I can't see
    >them being even close to 100%. Now if you don't have the source I can see
    >it, but then how do you know if the comments are accurate? Only by the

    tight
    >process you use (which I'm not saying is bad) can this happen. To verify
    >the validity of the comments you have to look at the code. So if you have
    >to look at the code anyway ... . If OO code needs to be commented then

    maybe
    >it needs to be refactored instead. And your walk throughs (code reviews)
    >should control this. If needed, a high level explaination at the top of
    >the class should be sufficient. If the code needs a comment and refactoring
    >doesn't help then add a comment.
    >
    >I'm glad you are able to do all you design up front. Not many places can.
    > Some can be done, but many(most?) can't. They end up performing iterative
    >design and commenting\coding and then changing both when the design changes
    >or new things come to light. Sometimes the coding has to be done first

    so
    >you see if it even will work. Current tools like XDE from Rational allow
    >you to take that code and view it via UML.
    >
    >A good IDE for and OO language that assists with refactoring (i.e. WSAD),
    >'reverse engineering' (i.e. XDE), unit testing (i.e. JUnit) and that versions
    >down to the method (i.e. WSDE) is probably more useful and important than
    >comments. Combine this with Code/Design reviews to ensure good quality

    code
    >(providing the reviewers know what it is) and you will have little need

    for
    >them.
    >
    >While I like most of the things done in your development process (esp Code
    >Reviews), it is the textbook/classical design process and in reality doesn't
    >work in many places for many reasons.
    >
    >Mark
    >
    >"Jason" <ice1066@hotmail.com> wrote:
    >>
    >>Comments are 100% vital to writing any kind of maintainable code. One

    of
    >>the rules I make all of my developers adhere to is writing of their comments
    >>before any of their code. Part of our detailed design process is to take
    >>the public API (All public objects and their public methods) and add the
    >>private methods and objects being used. After we've defined all of those
    >>in a Word document we then add processing instructions which are readable
    >>(part of the requirement is that business anlaysts, testers, and developers
    >>all have to be able to understand them).
    >>
    >>Once we have the detailed design document we build our objects and paste
    >>the processing instructions in as comments. These comments become the

    foundation
    >>for the code we write.
    >>
    >>When it comes time for the code reviews (we review code at three different
    >>parts of our life-cycle) the comments help us understand what the code

    is
    >>doing.
    >>
    >>It's even more important when noone has looked at a particular piece of

    >code
    >>for over two years and someone asks us to make an enhancement on it, we

    >can
    >>then read the comments quickly figure out what we need to change, and then
    >>modify the code.
    >>
    >>"Chris Maertz" <cmaertz@securitymicro.com> wrote:
    >>>
    >>>I believe comments are just as important as the code. When juggling multiple
    >>>projects (some of which you are working on jointly with others), it is

    >extremely
    >>>helpful to have comments that help you to orientate yourself when you

    are
    >>>switching from project to project.
    >>>
    >>>HOWEVER...I believe an even larger argument can be made for proper planning
    >>>and documentation of the project before you even open your IDE of choice.
    >>>Without the documentation and a plan, coding and commenting is a nightmare.
    >>>
    >>>
    >>>
    >>>"Glen Kunene" <gkunene@devx.com> wrote:
    >>>>How useful to you are code comments? Do you write them only out of habit
    >>>or
    >>>>do you believe they serve an important function?
    >>>>
    >>>>http://www.java-zone.com/free/articl...Kabutz06-1.asp
    >>>>
    >>>>Let us know.
    >>>>
    >>>>Glen Kunene
    >>>>Senior Editor
    >>>>DevX.com
    >>>>
    >>>>
    >>>

    >>

    >



  8. #23
    MarkN Guest

    Re: Are Comments a Waste of Time?


    I was jerking your chain about the OO language thing. I knew you where using
    an OO language. Kind of glad I did. Your explaination of your process is
    different from what you first said - because you provided more detail. I
    can't fault your process because I personally agree with [most of] if and
    it seems to work. I wish more places would develop this way. Unfortunately
    many places think that if you aren't coding you aren't working. They pick
    their tool and platform first (ie - "We 'know' VB and have Windows PCs so
    we need to hire Windows VB Programmers. Now how do we get the job done?
    Are you coding yet? What date will you be done?"). Great to hear someone
    is doing it right. I can't get anyone to buy into it ("We've developed software
    for years and never needed it before."). I guess part of the problem is
    that it may take longer at first to get it right - and maybe the second time.
    Same reason many are reluctanct to dive into Linux.

    But just because your process works well doesn't mean that it is the comments.
    In fact I would put a bunch of pennies on it that it is not. If you aren't
    writing your code in plain english then that might be part of the problem.
    Somethings will be 'cryptic' and will require a comment. When I look for
    code I look at the Object tree. If the packages, classes and methods are
    setup well and well named, then I need very little comments and I can find
    what I want. A high level explaination can be valuable but I look at that
    after I've found my class. Also, examples of how to use the classes are
    very useful - much more than any comment. Of course, if this is what you
    mean by comments then I guess I agree. This is much more like looking through
    the phone book than your example. Again, I'm not poo-pooing all comments.
    Just the fact that they are 100% vital. So if you can keep them correct
    and come under budget, then by all means do them. Then again with good,
    readable, refactored OO code you could come in way under budget! Keep
    up the good work.

    Mark


    "Jason" <ice1066@hotmail.com> wrote:
    >
    >I do use an OO language, it's just that I'm better at reading English.

    When
    >searching for something, I read the English description and when I found
    >what I'm looking for, I then look at the code, it's like looking for something
    >in the phone book, I look for the letter Ch's and then for the Cheetah's.
    >
    >Our design process is actually an iterative process. When we start the

    technical
    >side of a project we sit down and identify all the pieces of the puzzle,
    >do we need MQ Series, Siebel, VB, J2EE, Tuxedo, etc. After that, we figure
    >out what each piece needs to do. We then look at our skill set and figure
    >out if we don't know how to do something. If there's something we're not
    >sure of (design patterns are great), we build a prototype to test that one
    >piece, and it's just enough to prove to upper management that we can implement
    >the solution.
    >
    >Our testing cycle also has time built-in for code and design re-reviews.
    > We also have a process which keeps everyone visible of the changes going
    >on. Having the comments and the design up front, allow us to do impact

    analysis
    >and prioritize our changes according to cost and timeline.
    >
    >During initial development usually one person is responsible for a section
    >of code, however, once we hit system testing it could be anyone of 15 to
    >20 developers that go in and fix the code. The comments really make it

    easy
    >for someone to see what is going on without having to decode a semi-cryptic
    >statement.
    >
    >Keeping the comments in synch isn't really a bad thing. It's actually an
    >informal review process, because as you're updating the documentation you
    >look at the code and you sometimes realize, what was I thinking when I coded
    >this. The more times you read the code the better it becomes because you
    >can fine tune it.
    >
    >I would disagree with the statement that the methodology is not based on
    >the real world, since implementing this methodology we have seen a drastic
    >reduction in the number of defects our code has when it hits production,
    >change requests take less time, support costs are lower, developer productivity
    >is way up. The methodology we use is based on best practices from a number
    >of industries and has been customized for our environment. I'm not saying
    >it's perfect, it's the best, or it's the only way, but I remember the days
    >when we weren't using it, and I don't miss the pages at 3AM telling me another
    >production defect was found. I don't miss the days of working for 36 hours
    >straight because we were using the OTFP/CLH method (on-the-fly-programming/code-like-****)
    >and completely botched the design.
    >
    >My team has delivered its last five projects either on-time or ahead of

    schedule,
    >and we've been under budget each time. One release alone had 80 approved
    >change requests (a couple of rogue one's made there way in as well), and
    >our ability to turn them around so quickly was directly a link of our development
    >process working correctly.
    >
    >Becuase of this methodology my team has become the gold star team within
    >our company and we're working with other teams improve their processes.


    >A methodology alone will not solve your problems (the teams we're helping
    >use the same methodology and still have problems). It's how your direct
    >reports, you, your leaders, and his leaders manage the process.
    >
    >I'll step down off my soapbox now.
    >
    >"MarkN" <m@n.com> wrote:
    >>
    >>100% vital? You should start using an OO language!
    >>
    >>In the days of procedural coding[I speak of it as though it were dead -

    >I
    >>wish it was] comments were 100% vital. But with OO languages I can't see
    >>them being even close to 100%. Now if you don't have the source I can

    see
    >>it, but then how do you know if the comments are accurate? Only by the

    >tight
    >>process you use (which I'm not saying is bad) can this happen. To verify
    >>the validity of the comments you have to look at the code. So if you have
    >>to look at the code anyway ... . If OO code needs to be commented then

    >maybe
    >>it needs to be refactored instead. And your walk throughs (code reviews)
    >>should control this. If needed, a high level explaination at the top of
    >>the class should be sufficient. If the code needs a comment and refactoring
    >>doesn't help then add a comment.
    >>
    >>I'm glad you are able to do all you design up front. Not many places can.
    >> Some can be done, but many(most?) can't. They end up performing iterative
    >>design and commenting\coding and then changing both when the design changes
    >>or new things come to light. Sometimes the coding has to be done first

    >so
    >>you see if it even will work. Current tools like XDE from Rational allow
    >>you to take that code and view it via UML.
    >>
    >>A good IDE for and OO language that assists with refactoring (i.e. WSAD),
    >>'reverse engineering' (i.e. XDE), unit testing (i.e. JUnit) and that versions
    >>down to the method (i.e. WSDE) is probably more useful and important than
    >>comments. Combine this with Code/Design reviews to ensure good quality

    >code
    >>(providing the reviewers know what it is) and you will have little need

    >for
    >>them.
    >>
    >>While I like most of the things done in your development process (esp Code
    >>Reviews), it is the textbook/classical design process and in reality doesn't
    >>work in many places for many reasons.
    >>
    >>Mark
    >>
    >>"Jason" <ice1066@hotmail.com> wrote:
    >>>
    >>>Comments are 100% vital to writing any kind of maintainable code. One

    >of
    >>>the rules I make all of my developers adhere to is writing of their comments
    >>>before any of their code. Part of our detailed design process is to take
    >>>the public API (All public objects and their public methods) and add the
    >>>private methods and objects being used. After we've defined all of those
    >>>in a Word document we then add processing instructions which are readable
    >>>(part of the requirement is that business anlaysts, testers, and developers
    >>>all have to be able to understand them).
    >>>
    >>>Once we have the detailed design document we build our objects and paste
    >>>the processing instructions in as comments. These comments become the

    >foundation
    >>>for the code we write.
    >>>
    >>>When it comes time for the code reviews (we review code at three different
    >>>parts of our life-cycle) the comments help us understand what the code

    >is
    >>>doing.
    >>>
    >>>It's even more important when noone has looked at a particular piece of

    >>code
    >>>for over two years and someone asks us to make an enhancement on it, we

    >>can
    >>>then read the comments quickly figure out what we need to change, and

    then
    >>>modify the code.
    >>>
    >>>"Chris Maertz" <cmaertz@securitymicro.com> wrote:
    >>>>
    >>>>I believe comments are just as important as the code. When juggling multiple
    >>>>projects (some of which you are working on jointly with others), it is

    >>extremely
    >>>>helpful to have comments that help you to orientate yourself when you

    >are
    >>>>switching from project to project.
    >>>>
    >>>>HOWEVER...I believe an even larger argument can be made for proper planning
    >>>>and documentation of the project before you even open your IDE of choice.
    >>>>Without the documentation and a plan, coding and commenting is a nightmare.
    >>>>
    >>>>
    >>>>
    >>>>"Glen Kunene" <gkunene@devx.com> wrote:
    >>>>>How useful to you are code comments? Do you write them only out of habit
    >>>>or
    >>>>>do you believe they serve an important function?
    >>>>>
    >>>>>http://www.java-zone.com/free/articl...Kabutz06-1.asp
    >>>>>
    >>>>>Let us know.
    >>>>>
    >>>>>Glen Kunene
    >>>>>Senior Editor
    >>>>>DevX.com
    >>>>>
    >>>>>
    >>>>
    >>>

    >>

    >



  9. #24
    MarkS Guest

    Re: Are Comments a Waste of Time?


    I absolutely agree with Jason. Comments are an absolutely vital part of coding
    - they give strong hints as to what the intent of the developer is and allow
    for easier maintenance in the long run. Even modern OO languages do not
    obviate the need for comments - rather, the need is increased because of
    the complex relationships between objects.

    However, the /quality/ of the comments directly influences their effectiveness.
    Stupid comments like this only obfuscate the code and should be removed:

    // Add one to i.
    i++;

    However, short meaningful comments like this regarding the /intent/ of the
    code are absolutely essential to any worthwhile program.

    // Select the first valid hour.
    for( int i = 0; i < hours.length; i++ ) {
    if ( isHourInSchedule( hours[i] ) ) {
    timeHour = hours[i];
    break;
    }
    }

    No, comments are not 100% vital - but they are worth their weight in gold
    when you're the maintainer. Yes, you have to maintain them or all value
    is lost - but once you train yourself to do this you'll wonder how you did
    without them.

    In fact, when designing your classes, you can explain what you will do in
    a specific method using comments as pseudocode - thus flushing out any major
    design flaws /before/ you start coding. Implementation then simply consists
    of 'filling in' the code between your pseduocode - and voila, you have excellent
    commented code (in probably half the time)!

    IMHO, Jason has way of it. Yes, comments are not /absolutely/ vital, but
    neither are cars - but both will get you there and back again that much faster.
    I'd rather sleep at 3 AM. :-)

    Many regards,
    -Mark

    "MarkN" <m@n.com> wrote:
    >
    >I was jerking your chain about the OO language thing. I knew you where

    using
    >an OO language. Kind of glad I did. Your explaination of your process

    is
    >different from what you first said - because you provided more detail.

    I
    >can't fault your process because I personally agree with [most of] if and
    >it seems to work. I wish more places would develop this way. Unfortunately
    >many places think that if you aren't coding you aren't working. They pick
    >their tool and platform first (ie - "We 'know' VB and have Windows PCs so
    >we need to hire Windows VB Programmers. Now how do we get the job done?
    > Are you coding yet? What date will you be done?"). Great to hear someone
    >is doing it right. I can't get anyone to buy into it ("We've developed

    software
    >for years and never needed it before."). I guess part of the problem is
    >that it may take longer at first to get it right - and maybe the second

    time.
    > Same reason many are reluctanct to dive into Linux.
    >
    > But just because your process works well doesn't mean that it is the

    comments.
    > In fact I would put a bunch of pennies on it that it is not. If you aren't
    >writing your code in plain english then that might be part of the problem.
    > Somethings will be 'cryptic' and will require a comment. When I look for
    >code I look at the Object tree. If the packages, classes and methods are
    >setup well and well named, then I need very little comments and I can find
    >what I want. A high level explaination can be valuable but I look at that
    >after I've found my class. Also, examples of how to use the classes are
    >very useful - much more than any comment. Of course, if this is what you
    >mean by comments then I guess I agree. This is much more like looking through
    >the phone book than your example. Again, I'm not poo-pooing all comments.
    > Just the fact that they are 100% vital. So if you can keep them correct
    >and come under budget, then by all means do them. Then again with good,
    >readable, refactored OO code you could come in way under budget! Keep
    >up the good work.
    >
    >Mark
    >
    >
    >"Jason" <ice1066@hotmail.com> wrote:
    >>
    >>I do use an OO language, it's just that I'm better at reading English.


    >When
    >>searching for something, I read the English description and when I found
    >>what I'm looking for, I then look at the code, it's like looking for something
    >>in the phone book, I look for the letter Ch's and then for the Cheetah's.
    >>
    >>Our design process is actually an iterative process. When we start the

    >technical
    >>side of a project we sit down and identify all the pieces of the puzzle,
    >>do we need MQ Series, Siebel, VB, J2EE, Tuxedo, etc. After that, we figure
    >>out what each piece needs to do. We then look at our skill set and figure
    >>out if we don't know how to do something. If there's something we're not
    >>sure of (design patterns are great), we build a prototype to test that

    one
    >>piece, and it's just enough to prove to upper management that we can implement
    >>the solution.
    >>
    >>Our testing cycle also has time built-in for code and design re-reviews.
    >> We also have a process which keeps everyone visible of the changes going
    >>on. Having the comments and the design up front, allow us to do impact

    >analysis
    >>and prioritize our changes according to cost and timeline.
    >>
    >>During initial development usually one person is responsible for a section
    >>of code, however, once we hit system testing it could be anyone of 15 to
    >>20 developers that go in and fix the code. The comments really make it

    >easy
    >>for someone to see what is going on without having to decode a semi-cryptic
    >>statement.
    >>
    >>Keeping the comments in synch isn't really a bad thing. It's actually

    an
    >>informal review process, because as you're updating the documentation you
    >>look at the code and you sometimes realize, what was I thinking when I

    coded
    >>this. The more times you read the code the better it becomes because you
    >>can fine tune it.
    >>
    >>I would disagree with the statement that the methodology is not based on
    >>the real world, since implementing this methodology we have seen a drastic
    >>reduction in the number of defects our code has when it hits production,
    >>change requests take less time, support costs are lower, developer productivity
    >>is way up. The methodology we use is based on best practices from a number
    >>of industries and has been customized for our environment. I'm not saying
    >>it's perfect, it's the best, or it's the only way, but I remember the days
    >>when we weren't using it, and I don't miss the pages at 3AM telling me

    another
    >>production defect was found. I don't miss the days of working for 36 hours
    >>straight because we were using the OTFP/CLH method (on-the-fly-programming/code-like-****)
    >>and completely botched the design.
    >>
    >>My team has delivered its last five projects either on-time or ahead of

    >schedule,
    >>and we've been under budget each time. One release alone had 80 approved
    >>change requests (a couple of rogue one's made there way in as well), and
    >>our ability to turn them around so quickly was directly a link of our development
    >>process working correctly.
    >>
    >>Becuase of this methodology my team has become the gold star team within
    >>our company and we're working with other teams improve their processes.

    >
    >>A methodology alone will not solve your problems (the teams we're helping
    >>use the same methodology and still have problems). It's how your direct
    >>reports, you, your leaders, and his leaders manage the process.
    >>
    >>I'll step down off my soapbox now.
    >>
    >>"MarkN" <m@n.com> wrote:
    >>>
    >>>100% vital? You should start using an OO language!
    >>>
    >>>In the days of procedural coding[I speak of it as though it were dead

    -
    >>I
    >>>wish it was] comments were 100% vital. But with OO languages I can't

    see
    >>>them being even close to 100%. Now if you don't have the source I can

    >see
    >>>it, but then how do you know if the comments are accurate? Only by the

    >>tight
    >>>process you use (which I'm not saying is bad) can this happen. To verify
    >>>the validity of the comments you have to look at the code. So if you

    have
    >>>to look at the code anyway ... . If OO code needs to be commented then

    >>maybe
    >>>it needs to be refactored instead. And your walk throughs (code reviews)
    >>>should control this. If needed, a high level explaination at the top

    of
    >>>the class should be sufficient. If the code needs a comment and refactoring
    >>>doesn't help then add a comment.
    >>>
    >>>I'm glad you are able to do all you design up front. Not many places

    can.
    >>> Some can be done, but many(most?) can't. They end up performing iterative
    >>>design and commenting\coding and then changing both when the design changes
    >>>or new things come to light. Sometimes the coding has to be done first

    >>so
    >>>you see if it even will work. Current tools like XDE from Rational allow
    >>>you to take that code and view it via UML.
    >>>
    >>>A good IDE for and OO language that assists with refactoring (i.e. WSAD),
    >>>'reverse engineering' (i.e. XDE), unit testing (i.e. JUnit) and that versions
    >>>down to the method (i.e. WSDE) is probably more useful and important than
    >>>comments. Combine this with Code/Design reviews to ensure good quality

    >>code
    >>>(providing the reviewers know what it is) and you will have little need

    >>for
    >>>them.
    >>>
    >>>While I like most of the things done in your development process (esp

    Code
    >>>Reviews), it is the textbook/classical design process and in reality doesn't
    >>>work in many places for many reasons.
    >>>
    >>>Mark
    >>>
    >>>"Jason" <ice1066@hotmail.com> wrote:
    >>>>
    >>>>Comments are 100% vital to writing any kind of maintainable code. One

    >>of
    >>>>the rules I make all of my developers adhere to is writing of their comments
    >>>>before any of their code. Part of our detailed design process is to

    take
    >>>>the public API (All public objects and their public methods) and add

    the
    >>>>private methods and objects being used. After we've defined all of those
    >>>>in a Word document we then add processing instructions which are readable
    >>>>(part of the requirement is that business anlaysts, testers, and developers
    >>>>all have to be able to understand them).
    >>>>
    >>>>Once we have the detailed design document we build our objects and paste
    >>>>the processing instructions in as comments. These comments become the

    >>foundation
    >>>>for the code we write.
    >>>>
    >>>>When it comes time for the code reviews (we review code at three different
    >>>>parts of our life-cycle) the comments help us understand what the code

    >>is
    >>>>doing.
    >>>>
    >>>>It's even more important when noone has looked at a particular piece

    of
    >>>code
    >>>>for over two years and someone asks us to make an enhancement on it,

    we
    >>>can
    >>>>then read the comments quickly figure out what we need to change, and

    >then
    >>>>modify the code.
    >>>>
    >>>>"Chris Maertz" <cmaertz@securitymicro.com> wrote:
    >>>>>
    >>>>>I believe comments are just as important as the code. When juggling

    multiple
    >>>>>projects (some of which you are working on jointly with others), it

    is
    >>>extremely
    >>>>>helpful to have comments that help you to orientate yourself when you

    >>are
    >>>>>switching from project to project.
    >>>>>
    >>>>>HOWEVER...I believe an even larger argument can be made for proper planning
    >>>>>and documentation of the project before you even open your IDE of choice.
    >>>>>Without the documentation and a plan, coding and commenting is a nightmare.
    >>>>>
    >>>>>
    >>>>>
    >>>>>"Glen Kunene" <gkunene@devx.com> wrote:
    >>>>>>How useful to you are code comments? Do you write them only out of

    habit
    >>>>>or
    >>>>>>do you believe they serve an important function?
    >>>>>>
    >>>>>>http://www.java-zone.com/free/articl...Kabutz06-1.asp
    >>>>>>
    >>>>>>Let us know.
    >>>>>>
    >>>>>>Glen Kunene
    >>>>>>Senior Editor
    >>>>>>DevX.com
    >>>>>>
    >>>>>>
    >>>>>
    >>>>
    >>>

    >>

    >



  10. #25
    MarkN Guest

    Re: Are Comments a Waste of Time?


    public Object selectFirstHourInSchedule(Object[] hours)
    {
    for( int i = 0; i < hours.length; i++ ) {
    if ( isHourInSchedule( hours[i] ) ) {
    return hours[i];
    }
    }

  11. #26
    Jim-C Guest

    Re: Are Comments a Waste of Time?


    Kabutz is kaputz...

    Good show dip wade, you've just fueled the furnaces of lazy programmers everywhere,
    too inconsiderate to help out the next poor slob who has to maintain their
    crappy code once they move on. Maybe in your short career, you haven't had
    to do much maintenance yet because you were lucky enough to embark on a major
    new application. Just wait...

    I always laugh at this argument, it goes against common sense and I can list
    a hundred reasons why it's important but I'm sure they won't convince the
    disinterested. (If we're talking 100 to 1 odds in Vegas, I suspect you'd
    bet with me?)

    Writing good documentation is an art, just like writing good code is. And,
    it takes more discipline to exercise and practice that skill than coding
    simply because it's not as "fun". Unfortunately, you won't find a DEVX group
    dedicated to "documentation" like you will with JAVA or ASP. Too bad, there
    really ought to be one.

    Documentation has to be done as you code. Each line crafted like the code
    it should surround. Forget content/substance/long-term maintainability, those
    are the obvious attributes. How about this, sometimes a single comment line
    merely serves to visually separate a code-cept (that's code+concept) for
    the reader. Imagine that, a comment that really doesn't mean a whole lot
    but might aid a mental "breather" to the streaming mental puke that follows.


    You are correct about certain fad concepts taught in computer sci academia.
    Documentation will never go the way of "flow charts", infact, I predict it
    will be used more and more as a QA metric. (Have you ever read anything by
    Thomas McCabe or Edward Yurdon? I'm wondering what they're teaching these
    days.) It's my own belief that a simple ratio of LOD to LOC can depict much
    about the style -indeed the personality- of the programmer. For example,
    my colleagues often raz me about my "excess" documentation, but the truth
    is - one of them is too lazy to do it (although -I have to say in case he's
    reads this- he's gotten much better), the other for some reason revels in
    making his code more complex and obtuse. (Maybe that's a job security thing?)
    Funny thing though, none of them would mind working on my programs once I
    leave but they sure don't want to work on each others.

    Jim-C




Posting Permissions

  • You may not post new threads
  • You may not post replies
  • You may not post attachments
  • You may not edit your posts
  •  
HTML5 Development Center
 
 
FAQ
Latest Articles
Java
.NET
XML
Database
Enterprise
Questions? Contact us.
C++
Web Development
Wireless
Latest Tips
Open Source


   Development Centers

   -- Android Development Center
   -- Cloud Development Project Center
   -- HTML5 Development Center
   -- Windows Mobile Development Center