Should source code be the only software design documentation?

Question

I just came across Jack Reeves' articles asking "What is Software Design." I think he makes excellent points and now wonder whether source code should stand as the only software design documentation we create and leave behind. I think this fits in well with the ideas of DDD's Ubiquitous Language and could easily become readable documentation if all classes, properties, methods, etc. were created with meaningful names (i.e. a fluent interface). Documenting requirements as BDD stories first would complete the design.

Is this crazy? Have I misinterpreted Reeves' ideas? Is this what Agile is all about? Maybe I'm just having an "Aha!" moment that everyone else has already had, but I'm curious what others think about this as a valid idea.

Note: I highly recommend responders read--or at least skim--the article. I realize that face value appears insane, but Reeves makes some pretty excellent points. Of course, you certainly don't have to do so, but I imagine any responses not considering Reeves' points to be resounding "No!"s. :)

Answer 1

My opinion: Yes, that's just crazy - especially for large projects with lots of developers.

Answer 2

I have not read the articles, but in my opinion, the source code SHOULD NOT be the only source of documentation. There are different levels of documentation, and some belongs only in the source code, but there are some levels which do not belong in the source code.

For example, if you decide to use a particular technology, the justification for that decision should be documented, but not in the code. Business rules should not be documented in the code (although the comments in the code should refer to the appropriate external documents). However, if your code implements a particular design pattern, then it would be appropriate to place an explanation in the code.

If you are using an Agile methodology, your requirements in terms of documentation are relaxed somewhat, but you still need some documentation. In some cases, it will be more appropriate to put it in the code. However, in order to maximize the usability of your documentation in the future, portions of the documentation from the source code should be taken out and placed in external documents so that they can be more easily shared.

Answer 3

If we're talking about all of the design, I'm not sure where the GUI fits in this paradigm. I don't think source for a GUI will be as descriptive as a simple screenshot or a mock-up on paper...

Also, requiring a developer to read all the source code to understand what a group of classes does doesn't really sound all that appealing.

Also also, the source code isn't going to tell you why they did it this way...perhaps there were some barriers that caused them to go in a particular direction

So I'm gonna go with...it sounds a little nuts...

Answer 4

No. Source code can only tell you what the code does. It cannot tell you what it supposed to do.

Try refactoring buggy code without proper documentation sometime. You'll have to duplicated all unnecessary side-effects and bugs, because you don't know what's needed and what's not.

Answer 5

I understand the point of having the source code as documentation - as the source changes, the documentation changes effortlessly.

But, in my mind, this is very stupid in practice. When learning a new library, say a brand new 3D API - would you be interested in looking at the source code and the API documentation alone? Sure, they work well when you want to confirm that thingyMethod() indeed accepted a Foo first, and then only Bar.

But what happens when you have a more elaborate non-atomic question; "So, um, how do I get a guy rendered standing on an uneven surface while a monkey jumps up and down on his shoulder, shown with two camera angles"?

Would you RTFM? browse through all thousands of methods, figuring out which ones you really need to accomplish this? I sure would appreciate some kind of overview-y documentation, with up to date examples and tutorials in this case.

I, personally, despise this kind of thinking when trying out new things.

Answer 6

I think there are some things that simply cannot be implemented clearly - in other words, for some programs, you'll never be able to write source code that explains itself. And even if you can, you may not be able to write source code that explains itself to everybody else - you may understand it, but then again you'll have the experience and the technical knowledge that others may not.

Personally, I prefer to write concise code and detailed documentation (although my critics, if I had any, would probably prefer "cryptic" code and "verbose" documentation ;-)

Answer 7

Code should not be the only artifact.

IEEE 12207, Software Lifecycle Process, and its predecessors (Mil-Std 498, and DoD-Std 2167A) describe other documentation that should be associated with software develop efforts. Certainly not all are applicable every single time, but the customer and the development team should work together to decide how to tailor it.

Answer 8

It depends largely on the type of project that you're working on. But generally if the team is more than a few people - documentation can be helpful to remind everyone of the original intent of the software. Documentation should NOT be written for the sake of documentation - you should make sure that you have a well thought out reason for every single piece of (virtual) paper you produce - otherwise you're wasting time and therefore efficiency.

Answer 9

Certainly code should explain itself. In fact I really like Ruby language and his Rails framework: object oriented code is more readable than procedural one. When I develop simple Rails application I have no need to documentate the code, because it is already clear. On the other side, documentation is a must when numbers of people are involved in large projects.

Answer 10

No. Commenting can leave you with a nice "micro" understanding of the general layout and architecture of a system, but in order to understand the bigger picture of the greater birds-eye view architecture, I still think it's necessary to have external documents that give you an overall view of the grand scheme of things.

Also, most well-designed software starts out with a general understanding of where you're going, before you start to go there. That general understanding should be written down, and is considered part of the documentation. In order for a team to work together properly, it's helpful for all the members of the team to be on the same page. This general guidance is accomplished through some preliminary design documentation. Without it, you'll find developers that have gone rogue and are trying to design things the thought were discussed, but never were.

Answer 11

How could the code tell you what you chose not to implement, and why? This is a critical part of the design.

Answer 12

Thank you for pointing out some interesting essays, but I think you are misunderstanding Reeves.

Reeves' position is that the final design document is the source code, and that the creation of the source code is the software version of designing an airplane or radio or car. The fact that it's really easy to build software from the source code (production design) and absolutely trivial to make multiple copies obscures this - since there's a step of software production that is absolutely trivial compared to, say, alarm clock production or bridge building, our perceptions are thrown off.

Nowhere did I find a suggestion that source code is the only design document needed. Reeves encouraged other forms of documentation, provided that we all remember they are supplementary.

Source code is the final design document, the assembly instructions, but there is more to a software project than that. There are the requirements, which need to be recorded, so that it's possible to tell if the software actually does what it's supposed to do. (Given no actual requirements, I can write software really fast.) There are the lower level design documents, which are typically requirements documents for smaller parts of the program, and sometimes document the reasons for choices made.

Suppose I were designing vacuum cleaners, and I had a set of assembly instructions for a vacuum cleaner. Suppose I wondered if I could reduce the part count, or move some screws to better positions. With just the assembly instructions, I'd have to go through the design again. If I had documents with reasons why the screws go there and there, I could check if a different configuration would satisfy those reasons. Similarly, I can't reliably change software without knowing what it is supposed to do, and what the individual parts are supposed to do.

There's an old saying that, if the code and the comments disagree, they're both wrong. I've heard a version that, if they can actually disagree, the comments are bad, which may be going overboard. However, comments and other documentation should explain what individual pieces of software are supposed to do, and sometimes a high-level description of how they do it, but they should never get into a detailed implementation. I have worked with overly detailed documentation, and found it just as likely to be wrong as the accompanying software, and that it was harder to understand the two in concert than to understand the source code itself.

Answer 13

If you're going to write pages and pages of documentation describing in painstaking detail the exact behavior of the system then yes, the source code may prove to be a better form of documentation.

What the source code doesn't give you however, is a high level view. Things like flow diagrams can often give you a good overview of how a system works in seconds, as opposed to digging through every little function and eventually figuring out how all 3000 functions fit together.