Code is a mess...

Question

The code for Q2A is a pure PHP mess for a new comer. Gazillions of functions, incomprehensible program flow, bad commenting style, license is in every single file.

I am putting an effort to fix the following:
- Comments standards compliant to phpDoc.
- Removing the License from the files and pointing to the web page on this server and a copy of it in a file called LICENSE in the root folder of the package.
- fixing HTML code to be XHTML valid.

In later stages I would like to try and work on the program flow and the organization of the code to a more OOP approach and replacing all Javascript functionality with the use of the jQuery framework.

I would like to see the developer's views on this.

Also, is there a place we can observe the changes to the code? Something like a development site (bugs, revisions, patches etc.. )?

Answer 1

You can of course do any of this, if you're in compliance with the license, but please note that Question2Answer is not a pure "open source" product so you won't be able to distribute your modified version.

Comments

I am the initial poster, would you accept the modifications ?

---

Of all the issues you raise, phpDoc might be of interest, and the license is a fair point but a small issue.

I'm afraid your other suggestions would not be in keeping with my vision for Q2A. I don't see a need to use XHTML instead of HTML. An object oriented model would lead to large monolithic PHP files, and this would slow the system down (and there are PHP 4 issues). Finally, I didn't use jQuery because it's a large hunk of Javascript, of which Q2A would need a very small subset.

All of these things may of course change in future, but for now Q2A is focused on running quickly and efficiently on any version of PHP going back to 4.3.

---

using jQuery would open up a whole new area of abilities for the software. even introducing addons ;)

PHP 4 has reached "end of life" 2-3 years ago! That is a lot of time in web development... I urge you to reconsider.

---

I take your feedback on board, and if these become common issues for users of Question2Answer, it will change direction. In the meantime, even though PHP 4 has officially reached its end of life, it's still being used by a lot of people, including myself on some servers :)

Answer 2

In some ways I think the code is very well structured, and in others not. I think the structure has the "best intentions" at heart but in some cases is goes way too far.

For example, the way the functions in the theming engine are diluted right down to outputting single words is silly. The voting function outputs some wrapper code, then called voting_inner_html, which itself calls functions for displaying the arrows and vote count, and those each call several functions too. How many functions do you need to display a single number?!

PHP 4 is still in fairly high usage, although that doesn't stop you using an OOP structure. Don't know if it's really necessary, although I can see a few  places where it would work well. Even a static class for the methods in 'qa-util-string.php' would be a benefit.

Totally agree about jQuery - the library really isn't all that big and as you say it opens up a new world of simple features like AJAX for comments, answers, etc. The Javascript use will surely increase so why not convert to jQuery now while you can and save development time in the future?

Actually on that subject, one thing I would love to see changed is the reliance on POST for starting actions like adding answers. Seems silly to do a whole POST request just to display a form.

Comments

Thanks for your comments - let me respond to a couple.

First, believe me that I drove *myself* mad breaking up the theme HTML output into so many small functions. The reason it's done that way is to make it easy for people to change small parts of the HTML output (using an advanced theme) while still maximizing the chance of their changes being compatible with a future version of Q2A. Specifically, voting_inner_html() is called from the Ajax voting stub, so does need its own wrapper.

I hear you about using a POST to start actions. I did it this way because I wanted the question pages to be as light as possible, for the majority of cases where people (or search engines) are just reading content. While this could be addressed by loading the form Ajax-style, in general it's difficult to combine Ajax-driven DOM changes with the flexibility I wanted to offer for advanced themes. (This problem is exactly what lead to voting_inner_html() being created.)

In the fullness of time it might transpire that few people are using advanced themes, in which case that will shift the balance of priorities between Ajaxy animation goodness, and keeping the theme output simple. The decision will depend on how the product is generally used in the wild.

---

+1 to JQuery.. No, no, +10 ...