Refactoring of the code

Originally posted by: kno...@gmail.com

I've written up a UML class diagram to guide the refactor.

I spent almost a month writing out a significant number of rules and improvements for FlexPMD, fighting constantly with several silly design choices that greatly overcomplicated the problems.

As a design goal, I have focused on allowing the easiest possible growth and addition of rules, which I feel would be in the project's best long-term interest. Ideally, a rule should be addable through only the config file and the creation of the rule.php file.

The system I have outlined will convey the following advantages in comparison to our current and other systems I have seen:

1. Maintainability (...)
2. Unit Testing (or even test-driven development)
3. Simplicity of enhancement (The only thing a contributor needs to know is the available states - He doesn't need to read through thousands of lines of code.)
4. Avoidance of global state.
5. No abstract overhead or heavy coupling to abstract classes. (as long as rules fulfill the interface's contract faithfully, they are free to handle implementation details however they wish)
6. Encapsulation & Abstraction (Very little direct interaction is done with one or more of the components)
7. Top-down structure (Bottom level elements (rules etc) are not aware of higher level ones.)
8. Threading/Forking is very easily accomplished due to the top-down structure.

There are several design decisions still outstanding, and I will speak with an experienced colleague on Monday about the specifics. Feel free to add your input on any of the following:

1. To what extend should threading or forking be used.

2. State Tracking:

State tracking COULD be encapsulated into the rules themselves (and this would be ideal to encourage completely standalone rules), but this would mean passing every token to every rule, along with some other problems.

Alternatively, a dynamic object could be used to track state, but then it will need some clever wrapping code to avoid unintentional double state changes from multiple rules updating the same item.
(see http://www.ibm.com/developerworks/xml/library/os-php-flexobj/ for a brief guide on dynamic objects)

Labels: Maintainability
Cc: kno...@gmail.com

Originally posted by: tch...@hotmail.com

Externalise the checks.

Instead of all being inside the "PHPCheckstyle" class, the checks should be stored in a "Check" directory and inherit a "Check" interface or abstract class.

The "check" abstract class could have some utility methods :
* isActive()
* writeError()
* ...

Plus one abstract method : runCheck($token, $statementStack = null)

Question : How/When to instanciate the checks ? Creating a new one each time would not be efficient ? Singleton is bad ? Service Provider or Factory pattern ?

Problem : Lot of dependencies (the config, the reporters, some state flags).

Basic checks should be easy to externalise. More complex ones have a lot of dependencies. Others are not token-related but more global (cyclomatic complexity, NPath, ...).

Originally posted by: ukjbrooks

This is a tough one. Each check needs to be independent, but "hook" into the core, this would allow some of the none token-related checks to work too.

I guess we could see how PHPMD and PHPCodesniffer does this?

Originally posted by: tch...@hotmail.com

Dunno for PHPMD.

For PHPCodesniffer, each sniff register for a given token and when this token is met the sniff is called with the current token and the file token array. Each sniff is responsible for analysing the token and it's surroundings. This is a difference with PHPCheckstyle where we have static call sites for the checks and we have maybe more contextual information available.

Originally posted by: ukjbrooks

Depending on if we're rewriting everything, it may be worth trying that approach? I see the Factory pattern is common in this kind of thing.