Originally posted by Frank Carver:
In my coding, I make extensive use of automated unit tests and refactoring. Not only can I not see how to provide a unit test "safety net" to allow me to refactor the documents as I wish, but I can't even see how to set up practical acceptance tests so I know when to stop!
The XP books say (glibly) that if you find you need documentation, simply schedule it like any other task. I'm finding that documentation is not like any other task.
The soul is dyed the color of its thoughts. Think only on those things that are in line with your principles and can bear the light of day. The content of your character is your choice. Day by day, what you do is who you become. Your integrity is your destiny - it is the light that guides your way. - Heraclitus
Originally posted by Mark Herschberg:
What you really want is something like Javadoc, something which can automatically generate documentation from a rapidly changing codebase. I wish I had a tool like that, but I think we're a while off.
The soul is dyed the color of its thoughts. Think only on those things that are in line with your principles and can bear the light of day. The content of your character is your choice. Day by day, what you do is who you become. Your integrity is your destiny - it is the light that guides your way. - Heraclitus
Reid - SCJP2 (April 2002)
Originally posted by Frank Carver:
In general, I think I agree. But.
I reckon most directly code-related documentation is best conveyed by the code itself, maybe with a little JavaDoc style markup here and there to clarify what something is for.
Originally posted by Ilja Preuss:
Mhh, automated unit tests can be seen as documentation which is automatically always up to date (if you happen to run them regularly, of course).
Originally posted by Ilja Preuss:
I think that is the main reason why most agile advocates suggest to create these forms of documentation at the latest possible moment, so that you don't have to refactor it much...
Mark's Rule of Documentation:
Code is not complete without comments.
Originally posted by Mark Herschberg:
I think this is inappropriate for the reasons Frank mentioned--two weeks after writing the code sometimes I can't understand it (assuming no comments), let alone 6 months later.
Ilja's Rule of Refactoring:
Code is not completed when it seems to need additional documentation.
The soul is dyed the color of its thoughts. Think only on those things that are in line with your principles and can bear the light of day. The content of your character is your choice. Day by day, what you do is who you become. Your integrity is your destiny - it is the light that guides your way. - Heraclitus
Originally posted by Mark Herschberg:
While I think automated unit tests are great, they are not documentation! When someone opens up your files to modify your code, the unit tests won't explain to them how it works, and why it was implamented this way, and not another way.
The soul is dyed the color of its thoughts. Think only on those things that are in line with your principles and can bear the light of day. The content of your character is your choice. Day by day, what you do is who you become. Your integrity is your destiny - it is the light that guides your way. - Heraclitus
Originally posted by Mark Herschberg:
I wholeheartedly disagree. Code is complex, confusing, and can easily be misunderstood.
a few words interjected every few lines in the code, e.g. defining variables, describing the purpose of a for loop or non-trivial if statement, makes the code more readable.
The soul is dyed the color of its thoughts. Think only on those things that are in line with your principles and can bear the light of day. The content of your character is your choice. Day by day, what you do is who you become. Your integrity is your destiny - it is the light that guides your way. - Heraclitus
Originally posted by Frank Carver:
I really can't imagine any way of documenting this with the code or the unit tests, however clever the naming. I also can't think of anywhere in the (hundreds of) source files to put this sort of stuff which would stand any chance of being found by the people who might need it.
Reid - SCJP2 (April 2002)
Originally posted by Ilja Preuss:
With all due respect, but perhaps that is telling us something about the complexity of your code?
Originally posted by Ilja Preuss:
Does it have to be that way? {refering to complex code}
...
I don't write methods bigger than a few lines of code, generally. The method name tends to describe the purpose of these lines adequately. And I don't accept non-trivial if statements in my code.
I use the extract-method refactoring regularly.
Originally posted by Ilja Preuss:
Well, they explain how the code is supposed to be used and what results to expect. {wrt unit tests}
Originally posted by Frank Carver:
We now have a comment which is completely wrong. And worse, it's not an easy one to spot, confusing Math.min with Math.max is common at the best of times.
The soul is dyed the color of its thoughts. Think only on those things that are in line with your principles and can bear the light of day. The content of your character is your choice. Day by day, what you do is who you become. Your integrity is your destiny - it is the light that guides your way. - Heraclitus
Originally posted by Ilja Preuss:
In fact, I wondered wether you accidentally posted the unchanged code until you mentioned the difference... :roll:
The soul is dyed the color of its thoughts. Think only on those things that are in line with your principles and can bear the light of day. The content of your character is your choice. Day by day, what you do is who you become. Your integrity is your destiny - it is the light that guides your way. - Heraclitus
Originally posted by Mark Herschberg:
Perhaps I just haven't seen the light and my code is overly complex. I think it's reasonably well designed, although maybe I'm not quite in that top 1% of the field.
It's 5 lines of code, but I think those 2 lines of comments help clarify what's going on.
So you're saying that if you need to understand some code, instead of reading comments inbedded in the code, you should go read the test case code?
The soul is dyed the color of its thoughts. Think only on those things that are in line with your principles and can bear the light of day. The content of your character is your choice. Day by day, what you do is who you become. Your integrity is your destiny - it is the light that guides your way. - Heraclitus
Originally posted by Mark Herschberg:
And there-in lies the complexity. Again, maybe I'm missing something in all this refactoring, but the result is it makes a large number of methods and there is a lot of indirection.
Unless you have 80 character method names for all your methods, it can get comfusing what exactly each method does.
Often I have to jump back and forth between methods to figure out what's going on. It's all this indirection and trying to hold a half dozen methods in my head (or anyone's head) at once, which is likely to cause misunderstanding and mistakes to be made.
The soul is dyed the color of its thoughts. Think only on those things that are in line with your principles and can bear the light of day. The content of your character is your choice. Day by day, what you do is who you become. Your integrity is your destiny - it is the light that guides your way. - Heraclitus
Originally posted by Frank Carver:
It was brave of you to post that Ilja. I'm usually too ashamed of my own code to post it here. But now, both you and Mark have "put your code where your mouth is". I'll have to find some I'm happy enough with.
I sure felt a huge compulsion to "extract method" when I saw just how many times you use "game.getField()", though.
The soul is dyed the color of its thoughts. Think only on those things that are in line with your principles and can bear the light of day. The content of your character is your choice. Day by day, what you do is who you become. Your integrity is your destiny - it is the light that guides your way. - Heraclitus
Originally posted by Frank Carver:
Oh, and could you show us the tests for that behaviour, to show how much we can learn form them about this code. Thanks.
The soul is dyed the color of its thoughts. Think only on those things that are in line with your principles and can bear the light of day. The content of your character is your choice. Day by day, what you do is who you become. Your integrity is your destiny - it is the light that guides your way. - Heraclitus
Originally posted by Frank Carver:
{franks counter-points}
Originally posted by Frank Carver:
My questions are these. Given the obvious time pressure most of us work under, would it have been more valuable to the project to spend the time commenting this limit case, or writing a unit test for it? Would this problem (and, admit, it's not a particularly unlikely scenario) have been made better or worse if there were no comments at all?
Originally posted by Mark Herschberg:
We add documentation because code is hard to read, and we make mistakes reading it.
I can't imagine anyone who's had to maintain uncommented code, suggesting that we don't bother commenting.
Good point. That's why when your under time pressue you should always skip the unit tests and documentation. I mean, the code is more important, right? It'll probably work so doesn't need the tests, and it should be clear enough so save some time on documentation.
The soul is dyed the color of its thoughts. Think only on those things that are in line with your principles and can bear the light of day. The content of your character is your choice. Day by day, what you do is who you become. Your integrity is your destiny - it is the light that guides your way. - Heraclitus
Originally posted by Ilja Preuss:
Can you give an example of what you mean by the "why", please?
Originally posted by Ilja Preuss:
Of course, if the ThreadPool got used by outside clients without access to the source code, I would still want to add some javadoc.
What do you think?
Originally posted by Ilja Preuss:
Well, that is one way to react to hard to read code. The other is to make the code easier to read.
Originally posted by Ilja Preuss:
Well, in contrast to writing the comments, writing the tests will make me go faster, so it would be really stupid to skip them, wouldn't it? The same with refactoring the code to a clear state. (Mhh, that doesn't mean that I never fall into this trap myself...)
Originally posted by Mark Herschberg:
1) There may be multiple implamentations.
Consider the choice of a vector or array. You choose one, and you mention that reason why, e.g. we can't knwo how many records will be returned by the DB. This is probably a fairly low implamentation detail, which may not be covered in higher level docs. However, if the requirements change, e.g. the DB will always return 20 records at a time, then maybe an array would be a better choice. (We'll ignore other issues for why it won't be, this is a trivial example.)
2) The why may have to do with contraints.
For example, maybe there's a pre-condition, post-condition, or invariant, which should be met by the code or method.
3) The why may simply be there for clarity.
It will explain what the author was thinking.
The soul is dyed the color of its thoughts. Think only on those things that are in line with your principles and can bear the light of day. The content of your character is your choice. Day by day, what you do is who you become. Your integrity is your destiny - it is the light that guides your way. - Heraclitus
Originally posted by Mark Herschberg:
You don't need to comment becaue the class is internal. But then, some developer learning the value of resuse, makes the methods less private and starts calling them. Perhaps the methods get moved to new classes. In any case, now the methods are being used by other people.
The soul is dyed the color of its thoughts. Think only on those things that are in line with your principles and can bear the light of day. The content of your character is your choice. Day by day, what you do is who you become. Your integrity is your destiny - it is the light that guides your way. - Heraclitus
Originally posted by Mark Herschberg:
I think you missed my point. Again, maybe I'm missing something, but I don't think that's realistic. I think code is inherently hard to read. With all due respect, I see that statement as equivalent to:
Code is error prone.
Well, maybe you should write higher quality code.
It's not so easy to do.
That was my point. I got faster when I write comments, for two reasons...
1) I write comments before I write code. It gets me thinking about what I'm going to do, and structures my thoughts.
2) I feel more confident about the code I do write, because I know I can come back to it and quickly understand what's going on. I can also better integrate with existing code, because I can see what's happening there, too.
Do these arguments sound familiar? ;-)
[/QB]
The soul is dyed the color of its thoughts. Think only on those things that are in line with your principles and can bear the light of day. The content of your character is your choice. Day by day, what you do is who you become. Your integrity is your destiny - it is the light that guides your way. - Heraclitus
Originally posted by Frank Carver:
Don't get too smug, though, Ilja.
What happens if a developer forgets, loses concentration, or just plain screws up choosing a name for something, or which class a method should belong to, or whatever? The tests are coded to test the same names and responsibilities, so they pass.
If we take Ilja's viewpoint, that naming and responsibilities are important parts of the software, then we've just delivered an unknowingly faulty system.
If we take Mark's viewpoint that commented, working, code is what matters, there's no issue. The system is still in good shape.
Hmm. Anyone want to disagree that naming and grouping of code are just comments, with all the advantages and disadvantages thereof?
The soul is dyed the color of its thoughts. Think only on those things that are in line with your principles and can bear the light of day. The content of your character is your choice. Day by day, what you do is who you become. Your integrity is your destiny - it is the light that guides your way. - Heraclitus
Originally posted by Ilja Preuss:
a) the choice is driven by a requirement
In this case, the choice should be documented by at least one test - if I change the implementation so that the requirement isn't fulfilled any longer, a test should fail.
Originally posted by Ilja Preuss:
b) the choice is arbitrary
Well, why should we care about?
Originally posted by Ilja Preuss:
You don't need to comment becaue the class is internal. But then, some developer learning the value of resuse, makes the methods less private and starts calling them. Perhaps the methods get moved to new classes. In any case, now the methods are being used by other people.
You mean you have collective code ownership between team boundaries? (And I am meaning team in the sense of XP here - with tight collaboration and heavy communication.) I don't wonder that such a thing wouldn't work well... <http://www.javaranch.com>
Originally posted by Mark Herschberg:
I promise you this, your code will be used by people you never met, in ways you never intended. Thinking you don't need to comment the code because no one else will see it/use it is a Bad Idea(TM).
(This presumes you buy my previous argument that comments are necessary.)
But to answer your question directly... at my last company, we had roughly 4 teams, although teams people and teams were very dynamic. People often would modify each other's code. Not unilaterally, they would usually check first with the original author. You think the original author remembers what he wrote 4 months back, if it's uncommented? I certainly don't.
The soul is dyed the color of its thoughts. Think only on those things that are in line with your principles and can bear the light of day. The content of your character is your choice. Day by day, what you do is who you become. Your integrity is your destiny - it is the light that guides your way. - Heraclitus
Originally posted by Mark Herschberg:
Code is hard to write, full of bugs, and hard to maintain. I believe this to be fundamentally true in our current paradigm.
Perhaps some day well have sufficent tools and/or methodologies to write bug-free code, but not today. Look at the bug rates and maintanance costs of current software to confirm this.
Documentation, if used properly, can make code easier to understand and maintain.
Oh, but wait, people don't like to write documentation and won't update it. Now take that previous sentence and replace "documentation" with "tests." If you can get programmers to do one, you can get them to do the other.
The soul is dyed the color of its thoughts. Think only on those things that are in line with your principles and can bear the light of day. The content of your character is your choice. Day by day, what you do is who you become. Your integrity is your destiny - it is the light that guides your way. - Heraclitus
Paper beats rock. Scissors beats tiny ad.
Smokeless wood heat with a rocket mass heater
https://woodheat.net
|