Tibor,
IMHO every effort is welcome. Why not trying this way ? It may improve with
action...
Jacques
From: "tibor katelbach" <[EMAIL PROTECTED]>
> thx Si for your experience,
> Commenting code is always a plus but eventhough it is heavy , I stick to
> this idea as a usefull way to give and instant image of the algo behind a
> process without having to go into every piece that constructs it.
> This type of documentation should be maintained only when major changes are
> made because it's not a detailed description.
> Which isn't that often is it ?
> in any case as I go forward I continue to gather them, and could commit them
> into a docs folder of each process containing application if you guys find
> an interest in them.
>
> Regards
> Tibor
>
>
> On 7/12/06, Si Chen <[EMAIL PROTECTED] > wrote:
> >
> > Tibor,
> >
> > I tried to do exactly what you're suggesting about a year ago when we
> > developed the Financials module. I tried to write a document which
> > described all the business logic, data model, and processes. If you
> > look in the financials module there is a docs/ directory with a
> > TechnicalDocs file in DocBook SGML format.
> >
> > What I found was that it was extremely cumbersome and difficult to do
> > things this way, because I was writing a document and then writing
> > code. If later the code couldn't follow exactly the original design,
> > I'd have to fix the code, then fix the document again. It is not
> > impossible but would require a tremendous amount of discipline and
> > effort to do this.
> >
> > A better solution, in my opinion, is to comment the code better--
> > write more comments about the services, the Java methods, etc. that
> > talk about what is going on, and comment the SECAs about what process
> > each SECA is re-creating. This would create documentation which is
> > easier for developers to maintain and which another developer who is
> > familiar with the basic structure of OFBiz would be able to work with.
> >
> > This is what I'm trying to do know--as I look through code, I'm
> > putting more comments and committing them. I would encourage you and
> > everybody else to do the same. If you read through a service or some
> > code that could use better comments, please send in a patch.
> >
> > Si
> >
> > On Jul 11, 2006, at 8:46 AM, tibor katelbach wrote:
> >
> > > I agree, that is the pb with such docs, they are heavy to write,
> > > because the
> > > task is huge. But once it is done the main part is done, offcourse
> > > maintenance is heavy but it could also be a new way of spotting
> > > precisly
> > > what is new between versions and more readiable than a SVN upgrade.
> > >
> > > we all took the effort of understanding processes and this would be
> > > a way to
> > > share it. logs are shared but not exhaustive even the Verbose.
> > >
> > > I did it for quite a few processes and when I communicate these
> > > docs to
> > > other people needing a the same process, all they do is read it out.
> > > if what they need is in there , then they dig in.
> > > I often lost time by reading through loads of code and my answer
> > > was just
> > > waiting at the end,
> > > this way you go directly to the interesting section.
> > >
> > > offcourse this gets really interesting only if we all participate.
> > >
> > > just trying to help newcomers
> > >
> > >
> > > On 7/11/06, Chris Howe <[EMAIL PROTECTED]> wrote:
> > >>
> > >> I think that the easiest way to accomplish this is
> > >> through the logs. Documenting these processes for
> > >> reference would be too burdonsome and maintenance
> > >> would be quite tedious.
> > >>
> > >> --- tibor katelbach <[EMAIL PROTECTED]> wrote:
> > >>
> > >> > Hi everyone
> > >> > I've been tagging along an idea of documenting
> > >> > algorythms of ofbiz
> > >> > processes.
> > >> >
> > >> > Since I started working with ofbiz, as always I
> > >> > found myself having to dig
> > >> > into existing code
> > >> > I found that the clearest way to understand how
> > >> > modules work is to rebuild
> > >> > the algorithm behind a process .
> > >> > A process could be a complete run through from url
> > >> > to controller to to
> > >> > Service , run through the Service to result , to
> > >> > Screen ...etc.
> > >> >
> > >> > by writting down the main elements of a process this
> > >> > draws quite a clear map
> > >> > of the algorithm behind the process, and especially
> > >> > is easily transmitable and readable by others. This
> > >> > also keeps from having
> > >> > to run through all code , all processes which would
> > >> > be the next step after
> > >> > reading the algo.
> > >> >
> > >> > WDYT ?
> > >> >
> > >> > I think it would be enourmously enrichining for
> > >> > people like myself wanting
> > >> > to understand quickly what does what, and what is
> > >> > done behind the scenes.
> > >> >
> > >> > Sometimes these algos quite large for processes like
> > >> > the chekout process
> > >> > here's a sample I gathered up for the tellafriend
> > >> > process:
> > >> > I list Service , Maps, redirections... a std format
> > >> > needs to be set up
> > >> >
> > >> > Form : tellafriend
> > >> > input : message, sendTo, sendFrom
> > >> >
> > >> > >>>> controller event :
> > >> > org.ofbiz.product.product.ProductEvents"
> > >> > invoke="tellAFriend"
> > >> >
> > >> > >>> dans le service tellafriend
> > >> >
> > >> > [GenericEntity:ProductStoreEmailSetting]
> > >> >
> > >>
> > >> [bccAddress,null()][bodyScreenLocation,null()][ccAddress,null()]
> > >> [contentType,null()][createdStamp,2006-04-21
> > >> > 15:06:47.428(java.sql.Timestamp)]
> > >> > [createdTxStamp,2006-04-21
> > >> > 15:06:46.848(java.sql.Timestamp
> > >> > )][emailType,PRDS_TELL_FRIEND(java.lang.String)]
> > >> >
> > >> [fromAddress,[EMAIL PROTECTED](java.lang.String
> > >> )][lastUpdatedStamp,2006-04-21
> > >> > 15:06:47.428(java.sql.Timestamp)]
> > >> > [lastUpdatedTxStamp,2006-04-21
> > >> > 15:06: 46.848(java.sql.Timestamp
> > >> > )][productStoreId,910(java.lang.String)]
> > >> > [subject,${sendFrom} has sent you a
> > >> > link!(java.lang.String)]
> > >> >
> > >> [templatePath,/applications/petitbateau/templates/email/
> > >> tellafriend.ftl(
> > >> > java.lang.String)][xslfoAttachScreenLocation,null()]
> > >> >
> > >> > {
> > >> > templateData=
> > >> > [
> > >> > sendFrom= [EMAIL PROTECTED],
> > >> > message=qgfgsdf gsdf gsdf gsdfg sdf,
> > >> > [EMAIL PROTECTED],
> > >> >
> > >> pageUrl= http://localhost/petitbateau/control/product?product_id=94451
> > >> > ],
> > >> >
> > >> > [EMAIL PROTECTED],
> > >> >
> > >>
> > >> templateName=X:/X_Dev/sequoiaerp/applications/petitbateau/
> > >> templates/email/tellafriend.ftl,
> > >> >
> > >> > sendCc=null,
> > >> > sendBcc=null,
> > >> > subject= [EMAIL PROTECTED] has sent you a link!,
> > >> > [EMAIL PROTECTED],
> > >> > contentType=null}
> > >> >
> > >> >
> > >> >>>> dispatcher.runAsync("sendGenericNotificationEmail",
> > >> > context);
> > >> > >>>>org.ofbiz.content.email.NotificationServices"
> > >> > invoke="sendNotification(DispatchContext ctx, Map
> > >> > context)
> > >> > >>>>method prepareNotification(ctx, context);
> > >> > //builds the body of the
> > >> > mail by rendering the corresponding ftl
> > >> > >>>>if body != null
> > >> > >>>>dispatcher.runSync("sendMail", emailContext);
> > >> > org.ofbiz.content.email.EmailServices"
> > >> > invoke="sendMail"
> > >> >
> > >> >
> > >> >
> > >> > Regards
> > >> > Tibor
> > >> >
> > >>
> > >>
> >
> >
>
