How to understand the structure of this code better

[thadeusoares]

There is any doc detailing all the architecture of this code?

I want to contribute more, but I have a lot of doubts about it...

[ajmalton]

It is difficult to understand the code.

The documentation consists of a few files in the Technical section (see https://divinumofficium.com/www/horas/Help/technical.html), and inline comments, which are often wrong and always inadequate.

Fundamentally the code does this:

• read the requested parameters of hour, date, languages, and version;
• calculate the liturgical date from the above and the Kalendar rules;
• extract the details of the hour from the database, given the above, and finally
• output the above in HTML4, wrapped in various widgets and formatting

but these processes are not at all modular and it is not actually a pipeline even if it could be.

Also it is written in an old dialect of Perl and without regard for even elementary programming principles.

Soon (but not too soon) I'll post (and we’ll put in production) a comprehensive revision which takes a first step towards improvement, namely : declaring all the variables and turning on warnings, and rationalising the options processing a little. Just that is already non trivial.

Later (but not too much later) I’ll post to production a second step which will make the pipeline visible and modular, using objects and methods instead of global variables.

After that, we should be able to move the HTML to HTML5 with CSS, and expose a real mobile UI and real APIs on the network and standalone. But not before, because the code is far too brittle at present.

[thadeusoares]

Excellent, thank you for the explanation.

[FAJ-Munich]

Dear Andrew,
I am really appreciating all the effort long time contributors have been putting into this project and your explanation that the code is under major revision at the moment. Having started to actively contribute (with tiny commits so far) I have also tried to understand the code better and added comments in my own fork repository.
Do you think it would still be helpful for other contributors if I were to commit these code documentations to the main branch once sufficiently established?
Best regards,
F. from Munich

[ajmalton]

I think it depends on what the changes are.

Of course you will not be able to directly commit changes to the main branch of the upstream. You may create pull requests, of course.

Although above I said that there is a larger scale revision in progress, I think small changes that really do improve the clarity of the code, are worth making. As long as they don't change the behaviour, of course in fact, I think it's unlikely that any wholesale revision will happen all at once, so small changes are all we are likely to see, going forward.

[FAJ-Munich]

Thanks for your quick reply. I have no intention to alter the code 😄 ; I would just provide extra comments that may help others to understand better the logic behind it. Since I have an Apache running as localhost, I can do some tests before creating a pull request.