undefined reference

[exception]

Unfortunately, the code is pretty much unmaintainable because they have no use proper design and development methodologies and have instead concentrated on the algorithms involved.

Yes, I know of these problems. In CompSci people tend to say "programming is not CS", which is correct, but unfortunately, they neglect to admit that programming is a requirement for CS. It isn't taught properly at universities here, it's always said that the language doesn't matter (which is fine, as long as it is guaranteed that every student is really good in at least one language, which isn't the case). It is somewhat like in the math jokes, where the mathematician always comes up with the answer "A solution exists!". In CS, an algorithm is discussed, and whether it is a good idea to use it in a given language or not is not considered.
This is the situation as I know it; it is however not a situation I deem ideal. And I think that LP could help closing the gap between theory and praxis. When I took the first steps in programming, the first thing I did with code examples was deleting all comments and error handling to get the essence of the algorithm used - as clearly as possible. I think that many scientists try to do the same thing: write "clean" code which shows the new ideas as clearly as possible. Bad design, no error handling and poor maintainability/extensibility is as well a result as is the lack of proper testing of the theory, due to the overall unusability of the program. LP would allow to seperate main algorithm from "implementation detail", even allow high-level pseudocode formulation and seperate implementation.
In fact, my first larger LP project was a work for university, when I had to write a program and a work about the program, and have presentations about it. LP was ideal: with latex-beamer the slides could be made from the same data used in the work in no time, and the code documentation substituted the comments. I'd guess that about 50% of the work was saved due to this approach, while the resulting program was much better than usual "research code" I know (though still not really good, but that was a time problem).

As for the usability of LP for non-scientist programmers, I am coming to the impression that it is a matter of personal prefenrence. I wouldn't make LP a company policy, but I think I would have the programmers take a look at it and decide for themselves. When written well, old work can be understood better and faster in LP, but when this is not required (e.g. the old code is so well designed that it can be used as a "black box") it might introduce an unnecessary overhead. As for your initial arguments against it (I don't know to what extend your view has changed during this discussion), I think they are partly valid, but no criterion for exclusion. As every tool, it has advantages as well as disadvantages which have to be considered carefully.

[bnbertha]

Well gentlemen, I have found your discussion very interesting. LP is something I am not familiar with, but without rooting around the internet researching it, I am assuming from how you talk about it that you (@exception) are using it as an extra layer of abstraction in the design process that also enhances the documentation.

On a slight diversion from your main topic of LP or not LP, I have spent many hours discussing the merits of software documentation with a University professor (she is very experienced having sat on the ANSII C and POSIX committees). We came to several conclusions.

In general, documentation is often over used, usually being demanded by managers that have little understanding of why they are asking for it. It's main real uses are for development process auditing and training. I have rarely seen it used as a training aid and I have worked in and with more companies with more conventions and design methodologies than I care to remember. No software developer likes doing documentation, they need to see a purpose for it and be engaged in that reason otherwise it's something that gets nowhere near enough attention to detail.

As you both are no doubt aware, the software life cycle is generally split into two phases; initial development and maintenance. The only times I have seen documentation brought up to date at the end of a development phase is when the software is for an external customer. Even then it gets the bare minimum of attention.
During the maintenance phase, few programmers refer to documentation when making changes, regarding it as unreliable, the ultimate documentation being the code itself. This bypassing of documentation is especially so if the developer was part of the initial development team. So maintaining documentation during maintenance is often pointless. The only time I have seen this not being the case was when an external contracting company was given the code base for a major modification. Having up to date docs reduced their analysis time and reduced the contract cost.

I suspect, from your comments about LP, that any code maintenance would require changing the LP code which would ripple through to changes in the source code. Most organisations would regard this as unnecessary extra overhead as quite often the maintenance team are not the same as the initial development team and as Zaita pointed out, knowledge of LP is not widespread, so there would also be the extra overhead of training. I also agree with the concept of quick expansion and reduction of teams. I have seen this a lot. I believe Lockheed Martin even have special teams set up just for this purpose, they call them tiger teams and move them around projects as necessary.

I have seen many good ideas that have not progressed into widespread use, use of software evolution management and complexity analysis being my pet subject. I can see LP being really useful in several arenas. I suspect that the bottom line is that managers are rarely prepared to risk a project with trying out new ideas, sticking to tried and tested, 'safe' strategies and methodologies.

[exception]

Well gentlemen, I have found your discussion very interesting

Wow, I didn't expect anyone to read all this...

LP is something I am not familiar with, but without rooting around the internet researching it, I am assuming from how you talk about it that you (@exception) are using it as an extra layer of abstraction in the design process that also enhances the documentation.

Well, Zeita already posted two quotes, let me try to give a short overview with another from it's inventor, D.E. Knuth:

I believe that the time is ripe for significantly better documentation of programs, and that we can best achieve this by considering programs to be works of literature. Hence, my title: "Literate Programming."

Let us change our traditional attitude to the construction of programs: Instead of imagining that our main task is to instruct a computer what to do, let us concentrate rather on explaining to human beings what we want a computer to do.

The practitioner of literate programming can be regarded as an essayist, whose main concern is with exposition and excellence of style. Such an author, with thesaurus in hand, chooses the names of variables carefully and explains what each variable means. He or she strives for a program that is comprehensible because its concepts have been introduced in an order that is best for human understanding, using a mixture of formal and informal methods that reinforce each other.

So, the main idea behind LP is a new understanding of what programming actually means, with a very close relation to "documentation". But to provide for this task, it has another functionality: an additional layer of indirection on a pre-compilation basis. The "literate source", containing code- and documentation chunks, does not have to provide the source code in the order it will be "untangled" in the final sourcefile (just like functions have to be declared in the order they are called). For example, you could write

<<demonstration of LPs indirection>>=
point p, q;
try
{
  if(p==q)
    <<delete one of the points, since they are the same>>
  else
    <<create a directed line from p to q>>
}
catch(...)
  <<perform cleanup if anything has gone wrong>>
@

The code chunks (maked by <<...>>) used here can be defined anywhere in the document, using <<...>>=/*code*/@. So if you see it fit, you can make a chapter "Error Handling", where the cleanup code goes (e.g. if it is a scientific paper and the readers won't care much).
Defining a name twice expands it, so you could now write

<<perform cleanup if anything has gone wrong>>=
if(p==0)
@ This might happen if $some complicated latex formula$, as shown by \cite{supervisor}
<<perform cleanup if anything has gone wrong>>=
  delete p;
@

...which would be printed in this order in the document, neatly layouted with explanation, and produce

if(p==0)
  delete p;

in the untangled source. This opens a whole new possibility to let the code "document itself", by writing pseudo-code in the chunk names, giving the reader a faster way to go where he wants to go (e.g. to fix a bug): the chunks are linked when generating a pdf document as documentation (otherwise they are referenced by page number+ID). (One could jump in an IDE, but only on the function basis. And if you don't exactly know where the problem is, you can find it quicker by having an overview of the whole application an the abstraction level you need).

In general, documentation is often over used

Well, I'd rather say it is misused. The documentation I have to write and I get is absolutely unusable, not being up-to-date or complete being two of the main issues. I don't need such a documentation at all. On the other hand, if it were complete, up-to-date and written well, I think it would make a lot of jobs easier. LP helps to achieve all of these aims (by having all code contained in the documentation it urges the author to make it complete; by having the documentation opend when editing the code it urges the author to make it up-to-date; by having LaTeX' formatting power, it urges the author to make it clean, clear and 'pretty').
Another point is that it should be distinguished between different kinds of documentation: API, maintainer, end-user and administrator (whom did I forget?) all have different needs. Again, LP could provide for all (even the advanced end-user will be interested in an abstract overview of the applications structure).

I suspect, from your comments about LP, that any code maintenance would require changing the LP code which would ripple through to changes in the source code.

To stay "literate", yes. But the extracted source is not distinguisable from "traditional" code, so if you don't care about the documentation, no.

knowledge of LP is not widespread

That's right. But as I said, the code can be maintained without any LP knowledge, if required. So little risk is involved, really. Someone who can code in C++ can grasp the tool usage in less than a day, the actual "art" of LP is of course another matter. But the latter wouldn't be required so much for mainenance, when you only have to change something, not write it completely new.

Two things I'd like to make clear, if they weren't already:
(a) I don't want to talk anyone into using LP. It may have seemd that way in the beginning of the discussion, but that was due to some rather... controversal statements on both sides, I think
(b) When I first had to use LP, I pretty much had the same arguments against it Zeita has. I was "forced" to use it at university (had it not been my "best" prof, I would have chosen another course). Only when I had used it some time I accepted the fact that there are methologies other than the "traditional" way which are worth consideration. So I do understand your doubts. But I invite you to give it a try, when you have the time. It's a new programming experience.

[bnbertha]

It appears to almost be next generation doxygen. I happen to have to work with LaTeX and I don't care for it much though I can see uses for it. I find it frustrating and too particular about formating and white space. I will have a look at LP as much for curiosity as anything.

[Zaita]

It appears to almost be next generation doxygen

A good observation. And the code does seem to indicate this. I still think the code is unmaintable in comparison to standard development practices.

Zaita pointed out, knowledge of LP is not widespread, so there would also be the extra overhead of training. I also agree with the concept of quick expansion and reduction of teams. I have seen this a lot. I believe Lockheed Martin even have special teams set up just for this purpose, they call them tiger teams and move them around projects as necessary.

We tend to call them "developer pools". They are becoming more and more common, so much so I know companies who are going to solely rely on contractor developers to do all of their work now. It apparently, is cheaper in the long run.

<<perform cleanup if anything has gone wrong>>=
if(p==0) // Wrong, shud be != ;)
@ This might happen if $some complicated latex formula$, as shown by \cite{supervisor}
<<perform cleanup if anything has gone wrong>>=
  delete p;
@

vs

// Cleanup
if (p != 0)  // Fixed.
 delete p;

Ironically, the 2nd piece of code is more readable, more maintainable and easier to find bugs ;) Again, thats perspective.

I have found this to be a very interesting discussion on LP. I do agree we need better practices for documenting the design of our work and algorithms(I think code documentation is currently sufficient). I don't think LP fits that, the amount you have to type is considerably more than if it were a standard development technique.

What sort of extra time do you think it takes to write the code vs conventional development?

I know Test-Driven Development adds about 50% extra time to the coding of the application.

Edit: I re-reading it, I see it offers good potential for code-reuse by creating chapters. I think this is really a non-issue nowadays with good design techniques and solid OO structures.

[exception]

I just realized that the "delete p" example is utterly unusable. Suppose the deletion was "complicated" and required >5 LOC (e.g. some reference counting work). Otherwise it would of course be a stupid obfuscation to have an extra chunk for it, and your version is clearly more readable (brief examples don't really have the power to demonstrate it properly). And having something in between condition and action is of course bad idea, too. However, I personally like the "if condition <<expressive chunkname>>" style very much.

What sort of extra time do you think it takes to write the code vs conventional development?

Although it isn't 1:1 comparable (what exactly counts as "development"? E.g., writing documentation for conventional code? If I need 1h more and have 1 bug less, how much "longer" did it really take?), development time is comparable. This may be, however, dependent on the work you do and the approach you have. How many LOC/h do you produce, on average? I find that number so surprisingly low (well, I don't know it for you, but in the general case...) that it doesn't come as a surprise for me that "extra" time for LP is negligible, while a good summary on what you did yesterday might actually save some time (for me, it does, especially when "yesterday" means two months ago). But it really depends on the kind of work you are doing. As I pointed out, the C++ standard (second part) could be considered a LP for the STL declarations. The overhead here would be vast if the point was to provide the declarations. But if it were used as an LP, implementors would have saved the time to re-type all the declarations and could have started with the definitions right away. And the standard was written anyways, so one could as well argue that it was no overhead at all, but that it is an overhead to re-type... (the case is constructed, agreed. But re-use of of project-related artefacts is possible in many situations)

Furthermore, in research you cannot always predict every feature the end-product will have. Experimentation becomes a part of the development process, having an effect on the way the project goes. Thus the code and it's aims may change. Here, the literature-style helps to find the right focus and makes documentation of the experimentation results and resulting decisions easy/possible. If this isn't done, time is wasted upon thinking "why don't we just do <X>", where <X> already has been tested in an experiment and been found unsuitable.

It appears to almost be next generation doxygen

Doxygen creates an API documentation. LP is way beyond that. (I don't know what "next generation" is supposed to mean in this context, though).

[bnbertha]

Doxygen can create a lot more than just API docs. The next generation idea is that the doxygen sits amongst the code as comments, LP actually takes it to the next level by taking over the source code as well.