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
>> >
>>
>>
