http://ayende.comAyende @ RahienCopyright (C) Ayende Rahien 2004 - 2021 (c) 202660I think the the reasoning behind the design and implementation of a system is more important (and interesting) than the current state at some fixed point in time. /johan/ http://ayende.com/2573/working-software-over-comprehensive-documentation#comment9http://ayende.com/2573/working-software-over-comprehensive-documentation#comment9Wed, 20 Jun 2007 05:16:31 GMTFrans, > How is that thinking process look like? Don't you write things down, perhaps on a whiteboard or piece of paper? Draw a graph or image of the situation, think things through etc? There is a significant difference between the way I think and the way I write documentation. I don't need to write stuff for myself that makes sense on its own. Take a look at the diagram here: http://worsethanfailure.com/Articles/Drive-By_Architecture.aspx Does it make any sense? In the context of the discussion, it certainly did. But outside of it, it is a set of random lines, rarely useful. > Why not document these things along the way? Because if the documentation is meant to be useful, it should include a lot of things that are implicit in the way you think already. > The advantage is that it's recorded: the info is available for later reference The Apache foundation has a policy that all decisions must be made on the mailing list, because that keeps a log of what happens, I like this approach. http://ayende.com/2573/working-software-over-comprehensive-documentation#comment8http://ayende.com/2573/working-software-over-comprehensive-documentation#comment8Tue, 19 Jun 2007 16:26:07 GMTI have enjoyed reading this discussion about documentation. However, I have to agree formal documentation always ends up out of date. I think both design and testing are equally important. If you design good methods, properties and class names you can get a sense of what the intent of a component is. Encapsulation is very important to understanding intent and use. Unit tests are also extremely important for validating and refactoring. However, if your components are not designed well no amount of documentation, unit tests or developer talent will help you understand the code. Most of the time the code will be re-written (re-invented) (not refactored). http://ayende.com/2573/working-software-over-comprehensive-documentation#comment7http://ayende.com/2573/working-software-over-comprehensive-documentation#comment7Tue, 19 Jun 2007 15:02:05 GMTI've been down this road before, where you see something, forget why it was that way, and start to refactor only to then remember you already tried that or find out it doesn't work. But I don't think throwing some work away is always a waste of time. It's entirely dependent on your system and your developers. If you spend a ton of your time on your project reverse engineering old decisions, that's an indicator that you could use a little more design docs. If it doesn't happen all that often, you probably have the right balance. When I do want to document such things, I've created an internal team blog. When someone investigates/runs across/implements something, they can create an entry describing what they did and why, with the appropriate tags. That's pretty quick, and people find it easier to do it in blog format, and it's time stamped. Our Google mini crawls our blogs, so if you run across something strange, you can google for the class, or the subsystem, and likely quickly come across any relavent design notes. That works, as well as capturing the details of decisions in the defect tracking system and referencing particular defects in comments (and checkin comments). From what I've seen, It's at least as hard to write good documentation as it is to write good code, just as time consuming (if not more), and much less likely to be useful than a well tested and coded feature that the business needs to have. http://ayende.com/2573/working-software-over-comprehensive-documentation#comment6http://ayende.com/2573/working-software-over-comprehensive-documentation#comment6Tue, 19 Jun 2007 14:12:16 GMTThere's not a choice available. You also have to spend time on designing the proper class graph, or come up with proper names for your methods, classes, variables and unittests. This is also part of the whole software writing experience. Your choice is a bit odd. Unittests don't replace docs, as they're not a substitute. It's not that hard, as we all already write these docs :) Most software engineers, and I'm definitely sure you do this too, think before they write code. :). How is that thinking process look like? Don't you write things down, perhaps on a whiteboard or piece of paper? Draw a graph or image of the situation, think things through etc? Why not document these things along the way? My experience is that it won't take much longer than you would do it otherwise. The advantage is that it's recorded: the info is available for later reference. Add to that some discipline also mastered for class names, variable names, comments (!), keeping these things in sync isn't that hard either, you just have to force yourself to do so. IMHO the motivation to do so has to be there and often developers simply aren't motivated enough, because they won't consume the docs anyway: when these are needed, they're already moved on to other projects. IF I have to choose, I'd go for b. I get slaughtered by this choice perhaps, but it's motivated by the fact that the documentation reflects the intention of the code and why it is that way. With that I can make changes to the code. Sure, testability is a problem, but make no mistake: before unittests were widely used, people already wrote large pieces of software including OS-es. The motivation NOT to have docs seems to come from the assumption that the documentation WILL be bad. Though, where is it proven that the set of unittests given is 100% reflecting the complete set of use cases in all particular situations possible ? (if these things are even comparable ;)). That also assumes a thing, namely that the set of unittests is correct. I won't deny that, but why should a doc which is kept in sync have to be assumed to be bad? http://ayende.com/2573/working-software-over-comprehensive-documentation#comment5http://ayende.com/2573/working-software-over-comprehensive-documentation#comment5Tue, 19 Jun 2007 12:48:33 GMTFrans, the debate isn't about NO documentation, it is about which is more important. Given the choice - would you rather have a working application that had: a) Full unit test coverage but no documentation or b) Full documentation, but no unit tests Personally, I would go for (A) every time - because documentation is a leaky abstraction of the highest order. On top of the full unit tests, I would *love* lots of (GOOD) documentation. But it is all about where priorities lie. http://ayende.com/2573/working-software-over-comprehensive-documentation#comment4http://ayende.com/2573/working-software-over-comprehensive-documentation#comment4Tue, 19 Jun 2007 08:33:06 GMTLet's use ObjectBuilder from the entlib as an example. Anyone who hasn't read the code or its non-existing dev docs, go read the code and the unittests, then come back here and explain in detail how it works inside and proof you're right. You probably can't. Is it bad code? No, it's probably spendid code. Is it lacking unittests? not at all. One thing misses: you can't reverse engineer the process which led to the code by simply looking at the code: unittests aren't helping at all: they just test and show how to use the code from the outside, they don't show WHY it is setup on the INSIDE. If you can reverse engineer that from unit-test code, well, good for you and I'm sure your boss will be very happy to hear that you won't create a single bug ever again, simply because you can read code and reverse engineer every step in the process :). For the record, I can't. To some extend I can follow my own code without going back to the docs, but after a couple of years, and with hundreds of thousands of lines of code and a lot of classes, algorithms etc. etc., it's impossible. What I find a little funny is that you apparently forget which kind of comments were placed inside the nhibernate sourcecode before it went v1.0: things like "// I have no idea what this does" or "// why is this done here?" or similar comments. Apparently, the people who ported the hibernate code over to .NET didn't understand how it worked by simply looking at the code AND with all the unittests in mind. This is understandable, simply because the system internally is very complex, an o/r mapper IS very complex internally no matter what you do. By digging into sourcecode and understanding what it precisely does already takes a lot of time as you have to parse and interpret every line in the code and REMEMBER the state of the variables it touches! Can you do that in your head? I can't. Add to that the wide range of decisions one has to make to build a system like that and with just the end-result in your hand it's a hell of a job to come to the level where you understand why things are done that way. If that doesn't become clear, you have to assume why and if that's wrong (and why shouldn't it be, assumptions often are), you WILL have to wade through the same process again and again if you want to alter that piece of code, as you don't have that info present. You can't determine that from the code. Typical example: saving an entity graph recursively in the right order. That's a heck of a complex pipeline, with several algorithms processing the data after eachother, and the code branches out to a lot of different subsystems. If one can determine by JUST LOOKING AT THE CODE why it is designed the way it is, more power to him/her, but I definitely won't be able to do so. What I find surprising is that some people apparently think they can, with no more info than the end result of the code. What I find even more surprising is that it apparently is a GOOD thing that there's no documentation. It apparently is EASIER to read code, interpret every line, remember every variable's state it touches, follow call graphs all over the place, write down pre-/post- conditions along the way, THAN it is to read a design doc which describes why it is done that way and how it works and why B or C were rejected so you don't have to consider them again if the situation hasn't changed. Perhaps they're payed by the hour, I don't know. :) http://ayende.com/2573/working-software-over-comprehensive-documentation#comment3http://ayende.com/2573/working-software-over-comprehensive-documentation#comment3Tue, 19 Jun 2007 08:21:15 GMTjdn, I'm no where near as good as Oren. But I do use tests as documentation and have the same experience as him. I'm by no means as smart as he is. WatiN is a great example of a project where the tests were more informative than the documentation. Adam http://ayende.com/2573/working-software-over-comprehensive-documentation#comment2http://ayende.com/2573/working-software-over-comprehensive-documentation#comment2Tue, 19 Jun 2007 06:15:15 GMTAll well and good, but I think you using your own experience as proof for something is like having Michael Jordan using his own experience as a basketball player as proof for how all players should play and act. Which is why he hasn't really done all that well as a GM (and is true of almost all 'star' players who try to coach or GM). You aren't a representative sample. As I've mentioned previously, I've watched your first Hibernating Rhinos video (and need to remember to watch the others). You *really* aren't a representative sample. If it isn't clear, that's a compliment. http://ayende.com/2573/working-software-over-comprehensive-documentation#comment1http://ayende.com/2573/working-software-over-comprehensive-documentation#comment1Tue, 19 Jun 2007 02:37:24 GMT