code vs. design

[Ilja Preuss]

Originally posted by Valentin Crettaz in another thread:
Notice that I am not saying the source code is the only document we ever should produce. All I am saying is that writing code is less an activity of construction, but more one of design - and that it is the most authoritative design document we have. Applying a construction metapher to writing code might not be as insightfull as it seems. --Ilja Preuss
Tell me if I'm wrong but what you are saying is that "the code is the design".

Well, more of "the code is a design document, and the most authoritative one."

To me, the design is something that has the capability of giving an abstract view of the system in a much better way than the code. The design should be something very intuitive to a human being.

To me, the design is a property of a system. If i say a system has a OO design, I mean that the system makes use of polymorphism and encapsulation to manage dependencies. If I say a design needs to be improved, I mean that we need to improve the structure of the system. That structure is present not only in diagrams, but also in the code.
Again, I don't say that code is all we need - there are certainly aspects of the design which are hard to spot in the code (though they are certainly there) and so are better expressed using other techniques. (We could discuss how much actually could expressed in code, but that is even another discussion.)
My whole point is: writing code is not a construction (or should I better say manufacturing?) activity, but a design activity (though not the only one). Therefore when we think about how to make writing code more effective, comparing it to manufacturing cars might not be very insightfull.

[Kishore Dandu]

I would prefer design as a separate activity until coding starts. Then once a certain aspect of the overall system is being implemented, design can change or evolve depending on the pitfalls or reality of achieving the system.
In a sense, design should be considered as a separate entity that can be changed(or open for a change) depending on progress of the project(that sure includes implementation; i mean coding in your terms).

[Junilu Lacar]

I think it was Fred Brooks Jr. who wrote something along the same lines in "Mythical Man-Month" (or was it in "No Silver Bullet"?). He noted that the construction analogy is flawed and it would serve us better to use a biological(?) analogy instead, where we "grow" systems rather than "build" them. Unfortunately, the construction analogy is still being widely employed and I think it will be very hard to get rid of it.

[Lasse Koskela]

Originally posted by Kishore Dandu:
I would prefer design as a separate activity until coding starts. Then once a certain aspect of the overall system is being implemented, design can change or evolve depending on the pitfalls or reality of achieving the system.

In my last project where we built a custom integration platform, we did something like this -- I started out by sketching the architecture, with the main components enumerated etc., which lasted a couple of days including some superficial product evaluation. Once the development (i.e. testing, coding, refactoring) started, nothing in the original "design" was sacred. And nothing still is. The hard part is that external partners don't like the "nothing is sacred" part too much (but that's why we were prepared with an interface versioning scheme)...

[Stan James]

The "coding is design" argument is pretty neat. The kind of design that we might hope to complete before programming is at a certain level of abstraction. It has boxes and arrows and maybe some method names. But when it comes time to implement these things in code, there are still decisions to be made. What algorithms, how do I break up my methods, what inner classes, what variable names, any number of details the paper design would not have. If you think of all those decisions as detailed design, design goes on until the last compile before you ship.
This is kind of pointless academic debate unless you make something of it. Maybe you can find a way to erase the boundary between abstract design and code level design. Maybe you want to push more design responsibility to the coder. Interesting things can happen!

[Valentin Crettaz]

Thanks Ilja for starting this thread. As mentioned yesterday, I would have done it today anyway
Well, more of "the code is a design document, and the most authoritative one." --Ilja Preuss
I understand your point but I'm not sure "authoritative" is the most accurate adjective for what you want to express. When I look into the dictionary, I see that authoritative means "of acknowledged accuracy or excellence; highly reliable". I have yet to see code that is highly reliable or close to being excellent Computer scientists have always tried (and are still desperately trying) to find a way to correctly represent the design of software systems. I guess I'm not too wrong if I say that we aren't there yet.
My whole point is: writing code is not a construction (or should I better say manufacturing?) activity, but a design activity (though not the only one). --Ilja Preuss
To me writing code shouldn't even exist, and again, I do it every day and I love doing it, so I'm kinda shooting myself in the foot. But anyway, I just see that with the increasing complexity of software systems, if we persist on that path we won't be going anywhere because wirting code is far from being a productive activity. There are way too many mechanical things to take into account and to remember when writing code. Agreed, IDEs and UDEs really help us there. But these tools still have to evolve. Believe me Eclipse et al will not be the last generation of IDE tools. Call me an idealist if you want, but we need something (processes, tools, methodologies, all of them???) much more powerful if we want to build more reliable software that cope well with complexity.
Therefore when we think about how to make writing code more effective, comparing it to manufacturing cars might not be very insightfull. --Ilja Preuss
I agree with you and this is also where I like what Junilu brought up, namely that software development fits more to the biological analogy ("grow") than to the construction one ("build").
We could discuss how much actually could expressed in code, but that is even another discussion.) --Ilja Preuss
Not enough I fear... Again, going from the fact that a piece of code is one possible realization of a design of a software system, we have currently no reliable way of recognizing where the concerns of the customers are represented in the code. As a consequence, when the requirements change (and they do change), you have a hard time finding all the impacted places in the code that have to be revised.
This is kind of pointless academic debate unless you make something of it. Maybe you can find a way to erase the boundary between abstract design and code level design. Maybe you want to push more design responsibility to the coder. Interesting things can happen! --Stan James
As for the "pointless academic debate", I partly agree with you. It is true indeed that this discussion is deeply rooted in personal philosophical beliefs and how everyone sees software development.
This boundary between the abstract design and code-level design has been invented (*introduced*) by scientists willing to lower the complexity of constructing software systems. But, if you think about the essence of the software itself, there is actually no such boundary and I think this is one of the key point to look into in order to find a more reliable way of developing software.

[Stan James]

As for the "pointless academic debate", I partly agree with you. It is true indeed that this discussion is deeply rooted in personal philosophical beliefs and how everyone sees software development.

Absolutely. But to be really useful it would have to show up in the end product. Do people of different philosophies consistently build software with different qualities? (Hiding my opinion behind a grin)
As far as code being "authoritative" ... it is the only document that tells you how (deterministic) systems really work. I have a use case that says we validate password is at least 8 characters, but the system doesn't really do it. Sigh. The code does not lie. It never says there is any validation. It's kind of a smart-ass truism, but as true as any truism.
Actually it can be valuable if it leads you to never produce a document to communicate something that could be better communicated by the code or some translation of the code. Should I enter a javadoc that says this method returns a string when left alone javadoc would derive the actual return type from the code? If I could write misleading documentation a line or two away from the code, how much less reliable is a Word doc?

[Ilja Preuss]

Originally posted by Valentin Crettaz:
Well, more of "the code is a design document, and the most authoritative one." --Ilja Preuss
I understand your point but I'm not sure "authoritative" is the most accurate adjective for what you want to express. When I look into the dictionary, I see that authoritative means "of acknowledged accuracy or excellence; highly reliable". I have yet to see code that is highly reliable or close to being excellent

As long as the code is what the system is build from (by the compiler), it is the *only* design document which is guaranteed to accurately reflect the actual design of the system. The UML diagrams might be easier to understand, but if they don't reflect what the code really looks like, they are just imagination...

But anyway, I just see that with the increasing complexity of software systems, if we persist on that path we won't be going anywhere because wirting code is far from being a productive activity. There are way too many mechanical things to take into account and to remember when writing code.

Well, that somewhat depends on the programming language, and how we use it, doesn't it?

Again, going from the fact that a piece of code is one possible realization of a design of a software system, we have currently no reliable way of recognizing where the concerns of the customers are represented in the code. As a consequence, when the requirements change (and they do change), you have a hard time finding all the impacted places in the code that have to be revised.

In my experience, one of the best ways to deal with this problem is representing every feature in one or more automated acceptance test.

This boundary between the abstract design and code-level design has been invented (*introduced*) by scientists willing to lower the complexity of constructing software systems. But, if you think about the essence of the software itself, there is actually no such boundary and I think this is one of the key point to look into in order to find a more reliable way of developing software.

I agree. I would put my money on making the code more expressive. Your mileage may vary, of course...

[Ilja Preuss]

Originally posted by Kishore Dandu:
I would prefer design as a separate activity until coding starts.

Would you like to elaborate on why you'd prefer this?

In a sense, design should be considered as a separate entity that can be changed(or open for a change) depending on progress of the project(that sure includes implementation; i mean coding in your terms).

Mhh, I am not sure I follow you.
To me, the design is mainly driven by the needs of the code (actually my need to understand and change the code) and needs to be reflected in the code. So I don't know why you would want to separate it from the code.

[Lasse Koskela]

True story: earlier today I was asked to come up with a "nice picture" into the PowerPoint presentation I had sketched for an operational enhancement to the billing system we built some time ago. The responsible manager was afraid that people would not understand three sentences in plain English. Obviously, a wide scale of abstractions is needed, but I still concur that it's the source code that's the most authorative abstraction of the design to date.

[Kishore Dandu]

Originally posted by Ilja Preuss:

Mhh, I am not sure I follow you.
To me, the design is mainly driven by the needs of the code (actually my need to understand and change the code) and needs to be reflected in the code. So I don't know why you would want to separate it from the code.

So, all you guys are suggesting is to start some dummy coding and then think about design. You mean just look at requirements and start writing classes and dummy methods etc.
That sounds like a big joke for me(unless the system you are developing is very small in scale).

[Ilja Preuss]

Originally posted by Kishore Dandu:
So, all you guys are suggesting is to start some dummy coding and then think about design. You mean just look at requirements and start writing classes and dummy methods etc.

No, that's far from what I am suggesting.

[Warren Dew]

Originally posted by Stan James:
Should I enter a javadoc that says this method returns a string when left alone javadoc would derive the actual return type from the code?

Not if the only purpose of design documentation is to accurately document the design.
However, that's not the only purpose of design documentation. Another purpose - a purpose I view as more important - is to communicate to people who may work on or with the design in the future, sometimes in the far future. There are things that can be expressed far more succinctly in English than in Java, and those things are candidates for the documentation.
As for whether Javadoc or other comments close to the code are superior to separate Word documents, I would say yes, except when communicating to people who don't have access to the code. Keeping the comments physically close to the code generally does help keep them in synch.

[Ilja Preuss]

Originally posted by Warren Dew:
There are things that can be expressed far more succinctly in English than in Java, and those things are candidates for the documentation.

I agree in general, though I think that many people underestimate the potential expressiveness of code. And code does have one advantage over English - it's unambigiuous.
That's one of the reasons why I *always* first think about how to express something in code, and only if I fail at that make use of other documentation.

[Stan James]

English describes many things better than code. I guess that's why we're using it here. No argument atoll.
But any English descriptions run the risk of being out of date or flat wrong. Only the code is guaranteed to tell you what the software does, so rely on it as much as you can. BTW: Unit tests count. They can be great documentation. I just distributed some new utility classes and asked the team to read the tests first.
I like to keep written documentation at a high enough level of abstraction that it stays correct even when some low level decisions have to change, then refer to the code for the final details. Of course there is no perfect balance. Documentation that survives low level change may be so abstract or vague that it has no value. Even my highest level "boxes and arrows" have to be updated some times.

[Warren Dew]

Originally posted by Ilja Preuss:
I agree in general, though I think that many people underestimate the potential expressiveness of code. And code does have one advantage over English - it's unambigiuous.

And I would agree with that, as well. In fact, don't put a lot of comments in my function bodies - my identifiers are long enough that they can speak for themselves - and what I do put in are mostly summary statements about what the next section of code does.
On the other hand, for nontrivial public functions, I generally write a couple lines before the function declaration describing the purpose of the function. A descriptive function name can be sufficient to understand what's going on when reading code that already uses the function, since there's a lot of context to work with, but I find that when I'm trying to decide whether and how to use the function when writing new code, I often need more information. Sometimes even some detail is justified, such as when null arguments are acceptable and indicate a default condition.
In general, I think well documented interfaces are a great facilitator of code reuse. I use the Java standard libraries a lot more than I ever did the C++ STL, largely because the Java libraries are so well documented.
And I do differ from you in that I tend to write my comments first, before I write my code.
[ May 03, 2004: Message edited by: Warren Dew ]

[Valentin Crettaz]

Back from the week-end
As far as code being "authoritative" ... it is the only document that tells you how (deterministic) systems really work. I have a use case that says we validate password is at least 8 characters, but the system doesn't really do it. --Stan James
This issue is more related to synchronization between code and the underlying design. Technologies, such as Livesource and the like, should bridge that gap and make sure that everything expressed in a design document is implemented in the code. I agree, though, we are not there yet.
Actually it can be valuable if it leads you to never produce a document to communicate something that could be better communicated by the code or some translation of the code. --Stan James
Are you thinking about XDoclet, JSR 175 and related technologies?
As long as the code is what the system is build from (by the compiler), it is the *only* design document which is guaranteed to accurately reflect the actual design of the system. The UML diagrams might be easier to understand, but if they don't reflect what the code really looks like, they are just imagination... --Ilja Preuss
Agreed!! Again, we need some new technology(ies) that allow us to better link design documents with the code (Livesource and the like). MDA goes into that direction, but as of now, it still looks like a big dream to me.
Well, that somewhat depends on the programming language, and how we use it, doesn't it? --Ilja Preuss
Partly! The programming language is just one means we have invented to communicate our ideas to computers. I feel that the way we use programming languages these days is very limitative. Maybe I ask too much from them, but you have to agree that as soon as the system grows in size and becomes substantially big (50-100'000 LOC) you cannot have an overall view of the system, and thus, you cannot be sure that your code properly reflects what it has been written for. All I'm saying is that the code is good but we really lack *something* to assess it against. Nowadays we use test cases, this is good, but still not enough.
In my experience, one of the best ways to deal with this problem is representing every feature in one or more automated acceptance test. --Ilja Preuss
Agreed!! This sure is part of the solution...
I would put my money on making the code more expressive. --Ilja Preuss
I guess that the expressiveness of code is really limited by its grammar and semantics. You can make your code expressive up to a certain point beyond which it will not be possible for the code to be more expressive. I'm asking for much more expressiveness because complexity requires it.
There are things that can be expressed far more succinctly in English than in Java, and those things are candidates for the documentation. --Warren Dew
I agree in general, though I think that many people underestimate the potential expressiveness of code. And code does have one advantage over English - it's unambigiuous. --Ilja Preuss
But any English descriptions run the risk of being out of date or flat wrong. Only the code is guaranteed to tell you what the software does, so rely on it as much as you can. --Stan James
Until technologies for natural language processing are mature enough, using a human language to describe (or implement) software will not be really productive or even doable. On the other hand, I agree that since software are built by humans (at least in a foreseeable future), we should be able to build (or grow ) software systems using a human-like language. Third generation languages are pretty close to that except that their expressiveness has been reduced from the initial human vocabulary to that of a computer, and this is really limitative.
That's one of the reasons why I *always* first think about how to express something in code, and only if I fail at that make use of other documentation. --Ilja Preuss
This technique is a good one, although, I fear that junior developers would not be able to use it until they become senior The fact that you have to ask yourself that question (i.e. do I express that in code or in the documentation?) shows me that something is missing in the software development techniques we use today.
Bottom line: you all have to admit that things have to (and will) evolve otherwise we might just as well find another kind of job. When you come to think about it, software engineering is the youngest engineering area and maybe one of the fields that evolves the quickest. You can't just pretend that things will stay that way, that in 10 years we will still be programming in Java or C# the way we do today, that modeling techniques will still be regarded as only a way of documentating software, that we will not be able to properly synchronize code and design documents, etc. the list goes on and on. If you guys believe that, software engineering will be in danger. Personally, I need to know that technologies evolve even in ways that have not been imagined before or in ways that we deem as undoable or too futuristic. This is one of the few things that keeps me going and makes me believe that the future will be better
For people interested in new ideas for software development, below are two articles that provide some debatable (yet quite interesting) views:
http://java.sun.com/features/2003/01/lanier_qa1.html
http://java.sun.com/developer/technicalArticles/Interviews/livschitz_qa.html
[ May 03, 2004: Message edited by: Valentin Crettaz ]

[Ilja Preuss]

Originally posted by Valentin Crettaz:
This issue is more related to synchronization between code and the underlying design. Technologies, such as Livesource and the like, should bridge that gap and make sure that everything expressed in a design document is implemented in the code. I agree, though, we are not there yet.

There are two problems I see here:
First, by mapping UML to code, the tools have to reduce the expressiveness of UML. For example, I haven't yet seen a roundtrip tool which was able to handle association classes, let alone custom associatoin stereotypes or the like.
Second, to be helpfull in handling complex systems, the high level design documents need to abstract from the code. We *don't want* them to directly translate to code, but to express the ideas behind the code. I am not sure that it will ever be possible to effectively express those ideas in a way that tools will be able synchronizing the views between high level design and code.

MDA goes into that direction, but as of now, it still looks like a big dream to me.

Ditto...

The programming language is just one means we have invented to communicate our ideas to computers.

I don't think so. Language designers are very aware of the fact that code needs to be understood by humans - otherwise we would be programming in quite different languages, I'd think.

I feel that the way we use programming languages these days is very limitative. Maybe I ask too much from them, but you have to agree that as soon as the system grows in size and becomes substantially big (50-100'000 LOC) you cannot have an overall view of the system, and thus, you cannot be sure that your code properly reflects what it has been written for.

I actually don't think that I have to agree.
I agree that there is much code out there which makes it hard to understand complex (or even not so complex) systems, but I do think it is more because of improper use of language level design techniques.

All I'm saying is that the code is good but we really lack *something* to assess it against. Nowadays we use test cases, this is good, but still not enough.

Perhaps it is not enough because we typically don't write enough tests?

I guess that the expressiveness of code is really limited by its grammar and semantics. You can make your code expressive up to a certain point beyond which it will not be possible for the code to be more expressive. I'm asking for much more expressiveness because complexity requires it.

What kind of expressiveness are you looking for?

Until technologies for natural language processing are mature enough, using a human language to describe (or implement) software will not be really productive or even doable.

I don't think that it ever will be doable, simply because natural language is not unambigiuous.

On the other hand, I agree that since software are built by humans (at least in a foreseeable future), we should be able to build (or grow ) software systems using a human-like language. Third generation languages are pretty close to that except that their expressiveness has been reduced from the initial human vocabulary to that of a computer, and this is really limitative.

Good Smalltalk code can read very close to natural language. As the computer needs to understand the vocabulary - and needs to interprete it unambiguously to be reliable - I don't see a way around limiting the language used to that amount.

That's one of the reasons why I *always* first think about how to express something in code, and only if I fail at that make use of other documentation. --Ilja Preuss
This technique is a good one, although, I fear that junior developers would not be able to use it until they become senior.

In my experience, junior developers also don't write helpfull comments. :shrug:

The fact that you have to ask yourself that question (i.e. do I express that in code or in the documentation?) shows me that something is missing in the software development techniques we use today.

Actually I am not asking me that question. The question I am asking myself always is "how do I best express this in code?" Only if I fail to find an answer to that question do I use some other documentation - and I typically take that as an indication that I still need to learn something about how to express things in code. It's probably not something missing in todays techniques, but simply something missing in my personal bag of tricks.
But a small comment from time to time doesn't trouble me that much, either...

[Ilja Preuss]

Originally posted by Warren Dew:
what I do put in are mostly summary statements about what the next section of code does.

I prefer to put such a block of statements into their own method with a descriptive name. So instead of

// do foo
...
...
...
// do bar on fluff
...
...
...

I'd write

foo();
barOn(fluff);

On the other hand, for nontrivial public functions, I generally write a couple lines before the function declaration describing the purpose of the function. A descriptive function name can be sufficient to understand what's going on when reading code that already uses the function, since there's a lot of context to work with, but I find that when I'm trying to decide whether and how to use the function when writing new code, I often need more information. Sometimes even some detail is justified, such as when null arguments are acceptable and indicate a default condition.

As Stan already indicated, unit tests are quite good in documenting such things.

In general, I think well documented interfaces are a great facilitator of code reuse. I use the Java standard libraries a lot more than I ever did the C++ STL, largely because the Java libraries are so well documented.

Yes, JavaDoc is a nice thing when you don't have access to well designed source code. I still find that the latter is more critical to success, though.

And I do differ from you in that I tend to write my comments first, before I write my code.

Well, we actually don't differ here - I do this, too, since some years now. It's just that today I tend to write them in the form of JUnit tests, as I find them to be even more effective than JavaDoc...

[Warren Dew]

foo();
barOn(fluff);

That works when the interfaces are narrow, and I agree that's the preferred case. In some situations, though, the interfaces are broad, and the length of the argument list ends up making the code version much less succinct than the comment version.

As Stan already indicated, unit tests are quite good in documenting such things.

Sorry, but I've never yet seen a unit test that I can read and comprehend in less than ten seconds - which I can do with a properly written header comment for a function. Plus, if I have some nitty edge case that isn't covered by the unit test, it's less convenient to refer to the actual source than if I'm reading a comment two lines away from the actual function.

[Stan James]

Ilja - I recently had an experience exactly as you describe - turning comments for small blocks of code into method names. I was tickled that somebody who really needed to see it was watching at the time. I came from COBOL and other procedural languages where good functional decomposition makes things so much clearer. I'm sure many OO folk would object to me saying they're doing FD, but I don't know what else to call it.
Warren - I recently had a function based on the REXX language translate() function. Arguments are input, outTable, inTable. "For each character in input, if the character is found in inTable replace it with the character in the same position in outTable." is a little hard to parse. How's:

  assertEquals( "xne", translate( "one", "x", "o" ));
  assertEquals( "oyx", translate( "one", "xy", "en" ));

I used both doc & example. And this example:

   assertEquals("991231", translate("ghabde", "12/31/99", "abcdefgh" );

In REXX translate is frequently used to rearrange strings. Did you think that might benefit from some English doc?
[ May 03, 2004: Message edited by: Stan James ]

[Warren Dew]

I'm sure many OO folk would object to me saying they're doing FD, but I don't know what else to call it.

Well, that's what it is, so why not call it that? I've used the term "functional decomposition" several times here in the last week, and no one has objected - though maybe it's just because they didn't know what I meant by it until now.
Regarding the example, I find your english comment, "For each character in input, if the character is found in inTable replace it with the character in the same position in outTable" perfectly clear, provided the function declaration is "translate(input, outTable, inTable)". It takes me less than ten seconds to understand that.
Reading the asserts - presumably from the test case - didn't give me that. The first one is clear, for a single character replacement; I might not have understood it in ten seconds, but it wouldn't take much longer. However, my initial reading of the second one - "assertEquals( "oyx", translate( "one", "xy", "en" ));" - was "replace en with xy", which was incorrect. I didn't notice it was incorrect until I reread the english explanation, though, and I think this illustrates a situation where code doesn't do as good a job of communicating to a human being as it does to a machine.
The third assert is not very useful as documentation, in my opinion, because it takes too long to figure out which places the various characters are in. It is of course quite useful as a test.
So in answer to your question, I think the english descriptive phrase you provided is exactly the documentation that's needed, preferably just before the function declaration. I don't think extra documentation is needed in the test cases, though that's partly because I don't think test cases need to be documented as well - they aren't generally candidates for code reuse, and they don't generally need as much maintenance as regular code.
I suspect Ilya might argue that the function name could be clearer - I myself would use "substitute_characters" or something - but this is a good example of where it's difficult to come up with a function name that's as clear and complete as your two line comment.

[Valentin Crettaz]

First, by mapping UML to code, the tools have to reduce the expressiveness of UML. For example, I haven't yet seen a roundtrip tool which was able to handle association classes, let alone custom associatoin stereotypes or the like. --Ilja Preuss
And I don't believe I have ever said that one such tool exists!! BUT, the fact that none is available today does not mean that none will be available tomorrow. I apologize but I have to believe that tomorrow will be better...
Second, to be helpfull in handling complex systems, the high level design documents need to abstract from the code. We *don't want* them to directly translate to code, but to express the ideas behind the code. I am not sure that it will ever be possible to effectively express those ideas in a way that tools will be able synchronizing the views between high level design and code. --Ilja Preuss
When you say "We *don't want*" you talk for yourself or is it something you gathered from your interactions with other engineers? Ilja, you cannot seriously pretend that current software engineering technologies will not evolve anymore and that things will always be the same as they are now...
I don't think so. Language designers are very aware of the fact that code needs to be understood by humans - otherwise we would be programming in quite different languages, I'd think. --Ilja Preuss
Believe me, current programming languages will slowly (but surely) evolve into those "quite different languages" you mention. The evolution theory dictates it. Just think about the way scientists made assembly languages evolve over the years to become the object-oriented languages we use today. Please don't tell me that you think that object-oriented languages are the final step in the evolution of programming languages. They are good but still quite primitive for the tasks we will be up to in the upcoming years. Moreover, we also have identified many of their shortcomings and that's partly the reason why there is a big rise of aspect-oriented languages which nicely complements object-oriented languages. But, this is just another step in the evolution. The aspect-oriented paradigm will not be the last one either. Thinking that I will always build code the way we do now makes me become really anxious.
I actually don't think that I have to agree. --Ilja Preuss
That's your call, of course
I agree that there is much code out there which makes it hard to understand complex (or even not so complex) systems, but I do think it is more because of improper use of language level design techniques. --Ilja Preuss
Now, you are slightly coming to what I said. To me the "improper use of language level design techniques" is partly due to the way IDEs and UDEs are implemented and the degree of support they provide. If those tools were really supportive, you wouldn't have said what you just said because you would have gotten enough help from the tool for not being allowed to make improper use of the available techniques. What I'm saying since the beginning of the discussion is that tools have to be your partner when you use them for building software systems. For now, they are just merely passive. They automate a certain amount of mechanical tasks, but that's all. They have absolutely no intelligence and I think developers suffer from that. What's more, I'm SURE they suffer but they aren't even aware of it, and that's bad.
Perhaps it is not enough because we typically don't write enough tests? --Ilja Preuss
I can see that you are a test addict which I really don't mind I like testing, too, but I don't think that they are the absolute answer to the problem. Answering that testing will solve all problems (or at least enough so that the system works!!) is a pure illusion. As you know, there is no silver bullet. Test cases sure as hell are not bad, but they will definitely not save the world alone.
Sorry, but I've never yet seen a unit test that I can read and comprehend in less than ten seconds - which I can do with a properly written header comment for a function. Plus, if I have some nitty edge case that isn't covered by the unit test, it's less convenient to refer to the actual source than if I'm reading a comment two lines away from the actual function. --Warren Dew
Ditto. Moreover, natural language is much more, well, natural to humans than code. To me, a test case is nothing else than another piece of code, and thus, I don't see why it would be more easily read.
What kind of expressiveness are you looking for? --Ilja Preuss
Well, that's an excellent question which would deserve another discussion. What I can say is that I haven't yet found a language that provides the expressiveness I'm looking for. And I don't actually quite know what I want. It will be much clearer once I have found it. Basically, I would like to be able to express much more business related things in my code. I'm thinking about a sort of combination of doclets, JSR 175 and the like which I have played with a little but I still haven't fallen in love with any of them. I have some ideas but I will let them mature a little bit in my head before talking about them.
I don't think that it ever will be doable, simply because natural language is not unambigiuous. --Ilja Preuss
Techniques actually do exist to make natural language unambiguous.
I don't know about you, but I really enjoy this discussion. So pardon my insolence but it just appears to me that you always imply that something will never exist simply because it does not exist yet, don't you?
Good Smalltalk code can read very close to natural language. As the computer needs to understand the vocabulary - and needs to interprete it unambiguously to be reliable - I don't see a way around limiting the language used to that amount. --Ilja Preuss
Well, maybe I have badly formulated what I wanted to say. I'm still of the opinion that a language targeted at computers has to be limited in some ways, I'm not saying that the vocabulary or grammar should be infinite. I challenge you to find one single human language that has an infinite vocabulary and/or grammar. Even if this was not the case, I think any human language can always be sufficiently limited to be useful, comprehensible and unambiguous. Going from that, I don't see why a *pseudo-natural* language would not be appropriate for telling computers what to do and which tasks to carry out.
[ May 04, 2004: Message edited by: Valentin Crettaz ]

[Warren Dew]

Valentin Crettaz:
Techniques actually do exist to make natural language unambiguous.
True - but is the resulting language still natural?
There's a profession which specializes in making natural language documents unambiguous - the legal profession. The process requires a large amount of time and effort from highly educated professionals, and the results - legal documents that are as near unambiguous as possible - are generally considered much less legible than the average natural language document, quite possibly as difficult to read as a computer program.
I don't think that bodes well for significant productivity gains from "more natural" computer programming languages. Indeed, one could argue that the trend over the last two decades - ever since BASIC - has been away from naturalness in programming languages.

[Valentin Crettaz]

There's a profession which specializes in making natural language documents unambiguous - the legal profession. The process requires a large amount of time and effort from highly educated professionals, and the results - legal documents that are as near unambiguous as possible - are generally considered much less legible than the average natural language document, quite possibly as difficult to read as a computer program. --Warren Dew
Well, I wouldn't compare the legal profession with ours, but your comparison makes some sense to a certain extent. At least you agree that a computer program is not the easiest thing that a human can read.
I don't think that bodes well for significant productivity gains from "more natural" computer programming languages. Indeed, one could argue that the trend over the last two decades - ever since BASIC - has been away from naturalness in programming languages. --Warren Dew
So you think that the object-oriented languages we use today are less natural to a human than the previous languages (ASM, Lisp, Prolog, ...) that were in use some decades ago? I would have to disagree as I think that computer languages have become more and more natural to a human over the years and they should keep going that way. This is a good thing as we program machines not the other way around (at least until now ). So we have to come up with intuitive languages for working effectively. OO and AO languages are a good start in that direction, but the big challenge is still in front of us, I guess.

[Ilja Preuss]

Originally posted by Valentin Crettaz:
So you think that the object-oriented languages we use today are less natural to a human than the previous languages (ASM, Lisp, Prolog, ...) that were in use some decades ago?

I am not sure wether they really got more natural. How do you measure the naturalness of a language?
What I am sure about is that they got more expressive. And that is what I do care about.

[Ilja Preuss]

Originally posted by Valentin Crettaz:
First, by mapping UML to code, the tools have to reduce the expressiveness of UML. For example, I haven't yet seen a roundtrip tool which was able to handle association classes, let alone custom associatoin stereotypes or the like. --Ilja Preuss
And I don't believe I have ever said that one such tool exists!! BUT, the fact that none is available today does not mean that none will be available tomorrow.

Correct. I am just very sceptical that it will happen. After all, if I invent a custom stereotype to improve the expressiveness of a diagram, how should a tool connect it to code?

I apologize but I have to believe that tomorrow will be better...

Nothing to apologize for - I believe that, two. I am just betting on a different horse...

When you say "We *don't want*" you talk for yourself or is it something you gathered from your interactions with other engineers?

I am talking mainly for myself, of course, though my opinion is heavily influenced by interactions with other engineers. I wouldn't be able to come up with this alone...

Ilja, you cannot seriously pretend that current software engineering technologies will not evolve anymore and that things will always be the same as they are now...

I am not going to pretend that. I just don't expect it to evolve in that way.

Please don't tell me that you think that object-oriented languages are the final step in the evolution of programming languages.

No, won't tell you that.

Moreover, we also have identified many of their shortcomings and that's partly the reason why there is a big rise of aspect-oriented languages which nicely complements object-oriented languages. But, this is just another step in the evolution. The aspect-oriented paradigm will not be the last one either.

Of course not. But I also don't think that AOP has made programming languages "more natural". It just added tools for more effectively (or so we hope - it's still to early to really tell IMO) managing source code dependencies.

What I'm saying since the beginning of the discussion is that tools have to be your partner when you use them for building software systems.

Could you give an example of what you think the IDE should do for you?

I like testing, too, but I don't think that they are the absolute answer to the problem. Answering that testing will solve all problems (or at least enough so that the system works!!) is a pure illusion. As you know, there is no silver bullet. Test cases sure as hell are not bad, but they will definitely not save the world alone.

Yes, there is no silver bullet, but it's also somewhat unwarranted to complain about the lack of tools before having used the existing ones to full avail, isn't it? And experience seems to tell that with extensive automated testing you can get as far as getting only a handfull of bug reports a year.

Moreover, natural language is much more, well, natural to humans than code.

Not more natural to programmers, one would hope...

To me, a test case is nothing else than another piece of code, and thus, I don't see why it would be more easily read.

Because it's less complex, very sequential and straightforward.

Basically, I would like to be able to express much more business related things in my code.

Can you give an example of such a "thing" in natural language?

I don't think that it ever will be doable, simply because natural language is not unambigiuous. --Ilja Preuss
Techniques actually do exist to make natural language unambiguous.

Which makes them formal again, like todays programming languages, doesn't it?

I don't know about you, but I really enjoy this discussion.

Ditto!

So pardon my insolence but it just appears to me that you always imply that something will never exist simply because it does not exist yet, don't you?

I do think that things will evolve, will evolve in interesting directions and in directions noone of us might anticipate. I just don't see that programming languages will become more natural. It might be more likely that UML becomes the next programming language, but I am far from convinced that it will be a step in the right direction.

Well, maybe I have badly formulated what I wanted to say. I'm still of the opinion that a language targeted at computers has to be limited in some ways, I'm not saying that the vocabulary or grammar should be infinite. I challenge you to find one single human language that has an infinite vocabulary and/or grammar.

Infinite vocabulary is not the problem. Ambiguity is the problem - a problem AI tries to solve for decades, to not much avail til today.

Even if this was not the case, I think any human language can always be sufficiently limited to be useful, comprehensible and unambiguous. Going from that, I don't see why a *pseudo-natural* language would not be appropriate for telling computers what to do and which tasks to carry out.

Yes, there is nothing wrong with this. I actually think it's already done.

[Ilja Preuss]

Originally posted by Warren Dew:
Reading the asserts - presumably from the test case - didn't give me that. The first one is clear, for a single character replacement; I might not have understood it in ten seconds, but it wouldn't take much longer. However, my initial reading of the second one - "assertEquals( "oyx", translate( "one", "xy", "en" ));" - was "replace en with xy", which was incorrect. I didn't notice it was incorrect until I reread the english explanation, though, and I think this illustrates a situation where code doesn't do as good a job of communicating to a human being as it does to a machine.

Or perhaps the choosen test case is disadvantageous. What about
assertEquals( "1b3", translate( "abc", "ac", "13" ));

I suspect Ilya might argue that the function name could be clearer - I myself would use "substitute_characters" or something - but this is a good example of where it's difficult to come up with a function name that's as clear and complete as your two line comment.

Yes, and yes. I'd also like to explore how to implement the function so that it expresses what it does as well as possible.
First rough idea:

TranslationTable translationTable = new TranslationTable(inTable, outTable);
for (int charPos: input.charPositions()) {
  char charAtPos = input.getChar(charPos);
  if (translationTable.needsTranslation(charAtPos)) {
    input.setCharAt(charPos, translationTable.translate(charAtPos));
}

Well, this doesn't communicate that well the connection between the inTable and the outTable, but otherwise it seems to be quite close to the english description. Comments?

[Ilja Preuss]

Originally posted by Stan James:
I came from COBOL and other procedural languages where good functional decomposition makes things so much clearer. I'm sure many OO folk would object to me saying they're doing FD, but I don't know what else to call it.

There is nothing wrong with using functional decomposition in an OO design. In fact, it can be the first step in getting to a better OO design. For example, often you will find that some of the smaller functions can benefit from being moved to another class.

[Ilja Preuss]

Originally posted by Warren Dew:
In some situations, though, the interfaces are broad, and the length of the argument list ends up making the code version much less succinct than the comment version.

Then it's time for some refactoring - for example "introduce parameter object".

Sorry, but I've never yet seen a unit test that I can read and comprehend in less than ten seconds - which I can do with a properly written header comment for a function.

That's strange. What kinds of unit tests are you typically reading?

Plus, if I have some nitty edge case that isn't covered by the unit test, it's less convenient to refer to the actual source than if I'm reading a comment two lines away from the actual function.

If there isn't a unit test for the edge case, what makes you think that it's documented? Or, if it's documented, why did the author choose to not document it in a unit test? (I am not sure what "nitty" means, but it makes me wonder wether it really works when there isn't a test and the source code isn't obviously simple...)

[Warren Dew]

Originally posted by Ilja Preuss:
Or perhaps the choosen test case is disadvantageous. What about
assertEquals( "1b3", translate( "abc", "ac", "13" ));

That would be clearer. On the other hand, it doesn't catch some bugs that Stan's version does - in particular, if the function has a bug that prevents its moving backwards through the table. I'd rather let the test code focus on its primary purpose - testing - than dilute it by trying to make it substitute for comments.

Then it's time for some refactoring - for example "introduce parameter object".

Sometimes this is easy, sometimes it's less easy or gains less benefits. Following the "write for the present, not for the future" rule, it can be more efficient to spend 30 seconds writing a two line comment than 10 minutes refactoring.

If there isn't a unit test for the edge case, what makes you think that it's documented? Or, if it's documented, why did the author choose to not document it in a unit test? (I am not sure what "nitty" means, but it makes me wonder wether it really works when there isn't a test and the source code isn't obviously simple...)

Sorry, I wasn't clear. I'm talking about the possibility of an edge case that is neither documented nor tested for, because the original writer didn't think of it; in this case, I have to read the code to figure out what happens in either case. It's easier to move my eyeballs down two lines from the deficient documentation to the code than to open a new file so I can move from reading the deficient test case to reading the code.

[Warren Dew]

Valentin Crettaz:
So you think that the object-oriented languages we use today are less natural to a human than the previous languages (ASM, Lisp, Prolog, ...) that were in use some decades ago? I would have to disagree as I think that computer languages have become more and more natural to a human over the years and they should keep going that way. This is a good thing as we program machines not the other way around (at least until now ). So we have to come up with intuitive languages for working effectively. OO and AO languages are a good start in that direction, but the big challenge is still in front of us, I guess.
I don't think the object oriented languages are any more like natural language - I think the "like natural language" programming languages reached their peak with BASIC and SQL.
However, I don't think being more like a natural language is really the primary goal for programming languages. I think the primary improvement from structured languages to object oriented languages is that the object oriented languages can more directly express the characteristics of the solution domain - perhaps this is what Ilya means by "more expressive". This doesn't make them easier to read or learn - there's some evidence that it makes them harder to learn, since now you have to learn object design/decomposition as well as functional decomposition - but once learned, it makes it easier and more enjoyable to solve a problem with them.
I'll be a bit of an object oriented heretic here and say that I don't think that things like polymorphism and inheritance are really the biggest benefit of object oriented languages. I think the biggest benefits are in the areas of organization and encapsulation. The organizational benefits primarily involve putting the code near the related data structures, rather than having them widely separated. The encapsulation benefits primarily involve namespace management, so that you don't have to be constantly worried about collisions with areas of the code you're unfamiliar with.
I think some of the problems with present object oriented languages are becoming more clear. In particular, while I generally like Java, it tends to result in very verbose source code. For example, while the benefits of hiding data are enormous, one of the costs at present is that of writing accessor functions, which can triple the number of lines of code associated with simple data structures. So one example of where languages might further improve would perhaps be in allowing for some blurring between data access and function calls: if public data and accessor functions could be referenced in the same way, one could leave data members in the public scope initially, secure in the knowledge that they could later be moved to a more private scope and replaced in the public scope with accessor functions, without having to change any client code. And perhaps it might be good to figure out a way where one could move the data to a more private scope for write purposes without having to do it for read purposes as well.
By the way, what's an AO language?

[Stan James]

I find AOP pretty scary. You can read a pile of code and think you know what it does, then discover (or miss) an aspect that makes profound changes. Ivar Jacobsen had a couple articles about AOP and I think that's where I read some proposals for how to show them in an IDE. The ideas were promising, but I'm worried about only being able to comprehend code within an IDE. I still like paper some days.
Mye examples for translate were lousy. Some longer strings would be good with less confusing translations - someone used numbers into an alpha string which was much better. I know that after using REXX for years, I still had to go to an example when I wanted to do that rearrange trick. The REXX Language book used lots of examples in "input output" tables that made them easier to follow than the kind of asserts I wrote up there. I write lots of unit tests that look like:

input = "xyz";
expect = "abc";
runTest(input, expect);

because the actual test is a couple lines or so that I don't want to repeat over and over.

[Valentin Crettaz]

Correct. I am just very sceptical that it will happen. After all, if I invent a custom stereotype to improve the expressiveness of a diagram, how should a tool connect it to code? --Ilja Preuss
Could you give an example of what you think the IDE should do for you? --Ilja Preuss
Can you give an example of such a "thing" in natural language? --Ilja Preuss
What you proposed in the first sentence would be a good start!! How it should do it is just a matter of technological limitation in my opinion. I don't think this will never be possible. Basically, I would like to be able to teach my IDE how to understand my business domain so that it can proactively participate in the creation of the software and not just stand there and passively occupy my memory which would better serve other purposes... Again, I don't pretend to know how the technology will (or should) evolve but I still have the right to dream
Nothing to apologize for - I believe that, two. I am just betting on a different horse... --Ilja Preuss
Would you like to share its name with us?
I am not going to pretend that. I just don't expect it to evolve in that way. --Ilja Preuss
It is also important to me to discover in which ways you expect the technology to evolve. Would you like to talk about it?
But I also don't think that AOP has made programming languages "more natural". --Ilja Preuss
I don't think this is what I implied. I just said that AOP has brought elegant techniques for overcoming some known issues of OOP.
Yes, there is no silver bullet, but it's also somewhat unwarranted to complain about the lack of tools before having used the existing ones to full avail, isn't it? --Ilja Preuss
First, I can tell you that I have used a good deal of THE "big" tools available on the market and none of them really satisfied me. They all seem too generic to me. Second, I don't complain about the lack of tools, I just express the need for more evolved ones.
And experience seems to tell that with extensive automated testing you can get as far as getting only a handfull of bug reports a year. --Ilja Preuss
I don't object to that... The fact is that you apparently still get bug reports. You and me know the value of testing, so I won't discuss this aspect further.
Because it's less complex, very sequential and straightforward. --Ilja Preuss
To the condition that they have been well-written, which makes you start the problem of expressiveness again. I have seen test cases written by others, which hunt me down into my scariest nightmares.
Which makes them formal again, like todays programming languages, doesn't it? --Ilja Preuss
Well, not necessarly. It all depends on what you regard as formal, semi-formal and informal and then how that relates to ambiguity.
I do think that things will evolve, will evolve in interesting directions and in directions noone of us might anticipate. --Ilja Preuss
I think it is neccessary that people be chartered to anticipate the evolution of the technologies. In my opinion, there must be visionary people who bring sustainable ideas to the debate, and I strongly believe that such people do actually exist.
I just don't see that programming languages will become more natural. It might be more likely that UML becomes the next programming language, but I am far from convinced that it will be a step in the right direction. --Ilja Preuss
Fair enough
Although I don't like to regard UML as a programming language. Making it *executable* doesn't make it a programming language.
I'm curious to know what directions you think things will evolve in?
I don't think being more like a natural language is really the primary goal for programming languages. --Warren Dew
Maybe not. But it again depends on what you and I mean when we talk about natural language. When I say natural I actually mean highly intuitive to humans (among which we find programmers and developers ). I don't say that languages available today are not intuitive, because they are somehow, I just say that the techniques (languages, ...) we will use to develop software tomorrow will have to attain a degree of intuitiveness that has not been reached yet with current technologies. Just seeing that some big corporations (or spin-offs thereof) are walking along that path, kinda shows me that I'm not that far away from the truth.
By the way, what's an AO language? --Warren Dew
The aspect-oriented paradigm is nothing new, it just happens to have gained support lately. There are many papers available at http://www.aosd.net. Also a good introduction is the following Javaworld article I want my AOP!
I find AOP pretty scary. You can read a pile of code and think you know what it does, then discover (or miss) an aspect that makes profound changes. --Stan James
AOP can be really helpful for overcoming some drawbacks of OOP, but one thing that is absolutely necessary is a good tool support for controlling the impacts your aspects have on your code base. AJDE makes some primitive steps into that direction in that you can see in your IDE (Eclipse, JBuilder, SunONE, Emacs, ...) which parts of your code will be advised or receive additional member declarations, etc... Bottom line: My opinion is that the perenity of AOP will depend on the quality of tool support you will get.
[ May 07, 2004: Message edited by: Valentin Crettaz ]

[Valentin Crettaz]

However, I don't think being more like a natural language is really the primary goal for programming languages. I think the primary improvement from structured languages to object oriented languages is that the object oriented languages can more directly express the characteristics of the solution domain - perhaps this is what Ilya means by "more expressive". This doesn't make them easier to read or learn - there's some evidence that it makes them harder to learn, since now you have to learn object design/decomposition as well as functional decomposition - but once learned, it makes it easier and more enjoyable to solve a problem with them. --Warren Dew
Maybe we have been going in the wrong direction all this time as suggested by Ventana research: The Next Big Innovation In Software Is Not Software.
Basically, they say that we have always tried to adapt the business problem to an IT solution and that we should go in the exactly opposite direction, namely to identify the business problem first and then to apply (i.e., adapt) IT solutions to address the problem.
While this is debatable, it makes some sense to me as the primary goal of a company is to make business and IT should only be seen as a way of supporting it and not as the primary activity of the company. It seems that lots of companies have spent more time focusing on technological issues for supporting their business rather than on the business itself. Just think about the large budget increases for IT spendings (Slide 6) in the last ten years or so.
Anyway, I'm digressing from the initial subject of this thread...
[ May 07, 2004: Message edited by: Valentin Crettaz ]

[Warren Dew]

Thanks for the links on AOP, especially the Javaworld link.
The aspect oriented approach seems to me to have merit in principle. It does strike me that the automated weaving process has the same problems computer generated code always has - it can end up doing a lot more than one might really want. An automatically woven logger might be fine if you want a dump that you don't plan to search through unless something comes up, but it strikes me that a human manually working across the concerns - in this case the business and logging concerns - could do a much better job of writing code which was intended to alert operators to only those conditions they really needed to look at, especially if there's a good logging library available.
Even for the stuff automated weaving is good at, I'm not sure it's superior to handling the noncore aspects in another layer, rather than within the source code base. For example, if you really want security for every http transaction, perhaps it's better to handle the concerns by using https rather than by incorporating something into the same source code base as the business application. Are there good examples of where the aspect oriented approach is superior?
[ May 09, 2004: Message edited by: Warren Dew ]

[Lasse Koskela]

Originally posted by Warren Dew:
For example, if you really want security for every http transaction, perhaps it's better to handle the concerns by using https rather than by incorporating something into the same source code base as the business application.

True, but isn't the protocol handler (http/https) pretty close to an aspect?

Originally posted by Warren Dew:
Are there good examples of where the aspect oriented approach is superior?

I guess the EJB Container might be a good example of where the AOP solution can be superior to an OOP-only implementation -- the container's aspects can intercept whatever requests the EJBObject receives and takes care of applying any security restrictions and transaction demarcation required.
You might want a second and third opinion on that, though, since I'm definitely not too knowledgeable of the AOP scene.

[Valentin Crettaz]

For example, if you really want security for every http transaction, perhaps it's better to handle the concerns by using https rather than by incorporating something into the same source code base as the business application. --Warren Dew
True, but isn't the protocol handler (http/https) pretty close to an aspect? --Lasse Koskela
Yes, to some extent, we can see a protocol handler as some "aspect" taking care of all networking concerns...
I guess the EJB Container might be a good example of where the AOP solution can be superior to an OOP-only implementation -- the container's aspects can intercept whatever requests the EJBObject receives and takes care of applying any security restrictions and transaction demarcation required. --Lasse Koskela
Basically, AOP provides support for handling and managing crosscutting concerns while OOP offers techniques for dealing with localizable concerns. According to this, we can see that concerns such as transaction, security, exception handling, etc, crosscut your entire system and are thus not localizable within one "object". These are examples where you can benefit from the aspect-oriented paradigm. AOP and OOP do not compete against each other, they complement each other. This is one example where you can benefit from the advantages of both technologies.
The bottom line is that one of the biggest challenges of AOP will be to find a very expressive way to specify pointcuts in such a manner that makes it incredibly easy to interact with your code base without being too invasive. AspectJ has already achieved parts of that goal, but the language has some drawbacks. There are other actors in that play which I wouldn't underestimate, such as AspectWerks, Nanning, JAC, etc (you can find more here)
[ May 10, 2004: Message edited by: Valentin Crettaz ]

[Ilja Preuss]

Originally posted by Valentin Crettaz:
True, but isn't the protocol handler (http/https) pretty close to an aspect? --Lasse Koskela
Yes, to some extent, we can see a protocol handler as some "aspect" taking care of all networking concerns...

But not in the way it is implemented. It's much more like a service, in that it's not the protocol handler which decides when it is appropriate to use it. Or so it seems to me.

[Lasse Koskela]

Good point.