It was our own initiative. 4 of us integrated an existing team of developers and they were required to spit out detailed specs at every release.
This was a real-time redundant system to control production and transportation of electricity in the province of Quebec. That system had to show up 99.9999% availability. We have a vast network here, a single utility and the production sites (up north in the James Bay area ) are far from the consumers (mostly south near the St-Lawrence river). The software to control this as to be resilient otherwise the whole network can come down even if the network control is distributed in several centres. The idea of "duplicating" the content of the code in a document seemed to us a waste of time and money. So we came out with this tool. We had a significant number of modules to add to the existing system and many modifications to existing modules. Saved us many hours of document editing, reviewing and so on. It proved very efficient. Of course the requirement of having detailed documentation is not always present in most systems. But this one being critical, that requirement was unavoidable. Maybe I should look back at this and see how I could revive it. I used to comment heavily my code in my first ten years or so. I wrote a number of systems in assembly languages (20,000 to 40,000 lines) and it's quite natural to add comments when programming systems of that magnitude. I kept this habit for a long time even in high level languages or not so high level (C). Maybe I should experiment again and see if it's worthwhile. I was rather pissed off by the lacklustre of javadoc, especially when you need to add html tags to get some decent output. Our tools did not need any formatting hints. That was handled when calling the tool. The tags we used were there to indicate the sections forming the document, not the way they were to be presented. They were simple tags inserted at the beginning of a comment line. You could change the rendering of the document when calling the tool. That idea came from SGML that we were using at the time, WYSIWYG was just around the corner but we still had to typeset our documents using SGML tags. With SGML you postpone the presentation issues were they belong, when rendering the document on your laser printer or other rendering device. I may dedicate some time to this. Of course it has to be adapted to the languages used today and coders have to show some willingness to add significant comments to their code. If people are reluctant to do this then such a tool does not have any future :)))) Luc On Wed, 2008-12-31 at 17:23 -0800, Joseph Jones wrote: > > On Dec 31, 2008, at 1:29 PM, Luc Prefontaine wrote: > > > In the mid 80's I and others in a Fortran dev. team created a super > > javadoc. This beast was spitting out a FULL > > document in the editor used by office people. > > > > You would write comments in the code that were extracted and you > > would get a readable well formatted > > document after running the tool. Without the comments, the document > > looked ... empty and ugly. > > Missing items were as obvious as a nose in a face. > > > > Easier for code reviewer to control that, no need to read the code, > > read the document. If it does not make sense > > then go back to the coder. > > > > Coders had to add decent comments since the conventions were not > > only based on what you extract from the code > > (like javadoc) but also what is expected in comments so the document > > text content gets filled with decent content. > > When you force the coder to enter comments to fil a chapter > > introduction, well he/she has no choice. > > > > Of course it looks like if creating code is twice as complex but in > > fact you saved time when you need a system to be > > described very precisely. It also insured that comments were > > meaningful and in synch. with the code. > > > > > That sounds a LOT like Knuth's Literate Programming. Was there > influence from that or was this wholly based non your own? > > joe > > > > > --~--~---------~--~----~------------~-------~--~----~ You received this message because you are subscribed to the Google Groups "Clojure" group. To post to this group, send email to clojure@googlegroups.com To unsubscribe from this group, send email to clojure+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/clojure?hl=en -~----------~----~----~----~------~----~------~--~---
