I've run three contests so far on this blog - a beginner contest, an intermediate contest, and an advanced contest. The last contest wasn't quite as successful as I had hoped, and a lot of people weren't happy with the Flex 2 requirement. I promised another contest and today I'm delivering on that promise. As before, the number one requirement will be that you open source your contest entry. You do not need to actively support it, but you do need to allow folks to download it and use it. (Feel free to use the license of your choice though.) So let's get into the details.
Back when ColdFusion went from version 5 to MX, there was a code analyzer tool added to the ColdFusion administrator. This was (and still is) a handy tool to examine your files and point out potential problems. For this contest I'd like you to work on a new version of the code analyzer. Like the ColdFusion Administrator version, your version should let you pick files and then run the report. However, and this is the critical portion, I want you to focus on extensibility. What do I mean by that?
You should consider your code analyzer as two applications. One is the front end section that presents you with options and shows results. The second part is the actual engine that checks your code. You can imagine that engine as a collection of rules. So for example: "Don't use ParameterExists" That rule could simply do a regex check and return the line #s where the function is used. Another rule could be to use structKeyExists over isDefined. But the important thing is that the rules themselves should be as abstracted as possible. I'd suggest taking a look at Canvas for inspiration. All of the rendering rules for the wiki are written as CFC methods. The token type rules are written as CFCs. To be honest, that extensibility is one of the things I'm most proud of writing. You should use this for your inspiration.
To be clear - an entry with 2 rules, but a dang good extensibility engine will win over an entry with 200 rules and a worse engine.
So let's go over the rules:
- The application will allow the user to select a file or folders to be parsed. You can ask for extensions if you want, but by default it should scan CFM and CFC.
- The application will present a report of the issues found. Bonus points if you offer PDF and emailed results. You should also link to the file, potentially displaying the file using the same code color techniques BlogCFC uses.
- The application should allow for rules to be written. These rules define what the code analyzer looks for. These rules should be easy to use and install. The front end should offer a way to turn on and off these rules, but that is not required. So for example, if you don't agree with the use of StructKeyExists over IsDefined, you can simply turn it off. To be clear: This is the most important part of the application.
- Bonus points for good documentation of the rule API.
- Your application should run well in the ColdFusion administrator as a custom extension.
- As stated above, you must agree to share your code. I know that may sound scary. You are not promising to support the code. You are simply allowing folks to download it and use it. If you choose not to support it, I may host the application here.
The contest will run from now till the end of July, almost a full two months. Are there prizes? Of course there are! Prizes include:
- One copy of Fusion Reactor 2. (Not yet released, but may be by the end of this contest. Look for a review soon on this blog.) Thanks to Fusion Reactor.
- One copy of KTML. Thanks to Interakt.
- Will Tomlinson is offering a ColdFusion tee shirt and mug.
- I'm also working on other prizes as well.
Archived Comments
Just to be clear, you are the judge and jury on this, right? No all-star panel of judges? No "vote for your favorite"?
Yes. I had ideas for a contest where the actual code would decide the winner. For example, stock pickers or code that would "fight". Maybe later. But for this - yes - it's all me and my personal opinion. Of course, as with the other contests, it is more about the group discussion than anything else.
Trying to rack my brain as how to best apply "rules". First thought was "case", but no...
While the rules and engine are rather easy to implement, the issue is one of what rules are 'right'. While everyone would agree with IsDefined over ParameterExists (and a rule to warn if IsDefined does not have a proper scope), StructKeyExists is not universally accepted as better.
As someone who has 'suggested' some of the best practice rules we use, I can tell you that there has always been controversy over what to use. Not Len(var) vs. var="" for example.
Michael, I thought I had made it clear. The goal is an easy to extend system. Notice how I said a good system with 2 rules will beat a bad system with 200 rules. Do not get hung up on what the rules actually check for.
As it stands - your solution should let someone pick the rules they want to apply. So if they don't agree with the "StructKeyExists is better than IsDefined" rule, they can disable it. (Again, this is all described above, but just making sure folks get it.)
Just trying to be clear on things. :)
I already have this system built for my personal anti-spam system and have been meaning to release it as something for the community (time).
Looks like a good time to reiterate what I consider good rules on Blog of Fusion. :)
Ray,
You should send this out on the CF-Talk message list, maybe you will get more people interested in building a solution. I can see how this would be very useful, especially scanning old code.
You did know that there is a commercial product that already does this right?
It's the code review tool from activSoftware (formerly CFDev.com).
I'm not an employee of the company, but I did buy the software when it first came out. It works pretty well for code reviews.
Yep. But this will be an open source project. Also, what is wrong with reinventing the wheel? :) I've done that for all my projects and I found it to be a great way to learn.
The real point of this contest is for folks to try to write it - and for my readers and I to look at the entries and talk about it. What works - what doesn't work - etc.
[posted with Raymond's permission]
For those who may have questions with this contest, there is a ColdFusion-centric Regular Expressions list on House of Fusion:
http://www.houseoffusion.co...
This sounds like an intriguing project. I may have to sacrifice some sleep to enter in this contest.
For those using activsoftware for a list of rules, please note that their list is partially based on CF 5 and is not 100% true. For example IIF compiles down to the exact same code as a CFIF and is not slower at all. Might be harder for some to read, but that's a style thing, not a performance one.
There is NO speed increase using the
<CFSET variable="var">
syntax over the
<CFSET SetVariable('variable', 'var')
Not setting the overwrite argument in StructInsert does not slow the function down.
There are more that get a bit esoteric (such as the CFERROR mention) but the point is the same. Any rule you make should be something you have personal experience with and know for sure should be a rule or should be something that is well known by the community. If it's not, then whoever offered the rule should be able to put forward some good reasoning as to why it should be a rule.
(I put forward the IIF rule in CF 5 based on experimentation and I retracted it in CFMX based on more experimentation. But don't trust me, try it yourself) :)
This is going to be the best contest yet!
Ray,
Any restrictions on databases, etc? I know it adds some external dependencies, but it *would* allow for some cool tracking of fixes, etc over time and the ability to add things like blame reports.
Ray,
Any restrictions on databases, etc? I know it adds some external dependencies, but it *would* allow for some cool tracking of fixes, etc over time and the ability to add things like blame reports.
Roland - I'd rather it be SQL Server, MySQL, or Access, so that I can test it.
New prize listed.