Please allow my intro to properly define the scope of my question:
I'm still very new to the programming world. This all started for me when I had an idea for a software program, but no programming experience. I ended up going the outsourcing route to get the program, and after almost a year, we do have it live and functioning.
This specific program is written with php and is 100% web-based. We're using lots of ajax, jQuery, etc.
Now a year into it, I have been learning and learning wherever I can (lots of learning here!!!) I'm mainly focusing on Java now to build up to Objective-C and the iPhone fun (probably like 99% of all other newbie programmers out there).
I'm really learning so much, and one of the biggest things I'm learning about is proper commenting and scalability.
I'm seeing now that this job we just finished is very sorely lacking in both those areas. I am wanting to add and build upon this program, and not only do I not have much experience, but I'm seeing that it's really hard for me to even get an idea about the functions without these comments...
So my question is-what is the best course of action to begin to pick up the pieces on this program? A full re-write is out of the question, and I don't think is needed.
I'm sure this is not the first time some newbie programmer, software developer has been down this path...what do others do here?
Is it common for a programmer to come into a project very far along and then "clean up" the mess in order to make things move forward productively?
If this is the wrong place for this question (and I understand it may well be) can someone point me to where this would be more appropriate?
Thanks!
Joel
We call it "refactoring" and it's an important part of programming.
First, you must have a rock-solid set of automated tests. Usually we have unit tests that we run with a unit testing framework.
http://www.testingtv.com/2009/09/24/test-driven-development-with-refactoring/
Then you can make changes and run the tests to confirm that nothing was broken by your changes.
In some cases, you have to "reverse engineer" the tests around the existing programs. This is not very difficult: you have to focus on the interfaces that are "external" or "major" or "significant".
Since you're reverse-engineering, it's hard -- at first -- to determine what should be tested (because it's an important external feature,) and what should not be tested (because it's an implementation detail.)
I'm really learning so much, and one of the biggest things I'm learning about is proper commenting and scalability.
First, I'm curious what you've learned about "proper commenting" as this varies drastically. For some, it's documenting every class and function. For others, it may be documenting every line of code or no code at all.
After having gone through some of the different phases above, I'm with Uncle Bob Martin who, in Clean Code, says that you document decisions, not what the code does. The code itself should be readable and not need documentation. By adding comments describing behavior, you've created duplication that will eventually become out of sync. Rather, the code should document itself. Using well-named functions and variables help describe exactly what the other intended. I'd highly recommend Clean Code for a full discussion of these concepts.
As for scalability, it's usually something that you want to build in. Scalability might be a function of good design, or a proper design for the requirements, but poor design will make scalability a nightmare.
I'm seeing now that this job we just finished is very sorely lacking in both those areas. I am wanting to add and build upon this program, and not only do I not have much experience, but I'm seeing that it's really hard for me to even get an idea about the functions without these comments...
I see this as an indicator of one of two things:
That the code isn't well written. Yeah, that's highly subjective. -OR-
That you don't yet fully understand everything you need to. -OR-
A little bit of both.
Writing good, intention-revealing code is hard and takes years of practice.
So my question is-what is the best course of action to begin to pick up the pieces on this program? A full re-write is out of the question, and I don't think is needed.
As other posters have mentioned, Refactoring. Refactoring is the process of changing code to improve readability and usability without changing functionality. Get a good book on refactoring, or start reading everything you can online. It's now a critical skill.
Is it common for a programmer to come into a project very far along and then "clean up" the mess in order to make things move forward productively?
Unfortunately it is. It takes a lot of diligence to avoid falling into this trap. Try to make your code a little bit better every day.
I don't know about this being the wrong place or not, but I'll answer as I can:
Is it common for a programmer to come into a project very far along and then "clean up" the mess in order to make things move forward productively?
Yes, in my experience this is very common. I have been doing contract work for over 10 years, and I can't count the number of times I've had to come in and clean up something hastily put together to either make it scale or to be able to add functionality onto it. This is especially common when you outsource the programming to another company, the incentive there is to get it working and out of the door as quickly as possible.
So my question is-what is the best course of action to begin to pick up the pieces on this program? A full re-write is out of the question, and I don't think is needed.
I don't know that there is a "good" answer to this question, the only thing I can tell you is to take it one method at a time and document what they do as you figure them out. If you still have access to the people that initially wrote the program you can ask them if they could give you documentation on the system, but if that was not included as part of the original work spec I doubt they are going to have any.
I'm really learning so much, and one of the biggest things I'm learning about is proper commenting and scalability.
As you have found on your own, proper commenting is important, I'm not convinced on the importance of building scalability in from the beginning, going by the YAGNI principle. I think that as any program grows it is going to go through growing pains, whether that is scalability or functionality. Could someone have built twitter from the start with the kind of scalability in mind that it currently needs? Possibly, but there is the very real possibility that it would flop.
Is it common for a programmer to come into a project very far along and then "clean up" the mess in order to make things move forward productively?
It's definitely common for pretty much EVERY programmer :)
Having said that, remember the IIABTFI principle. If It Ain't Broke, Don't Fix It.
Understanding how the program works and what the pieces are is useful.
Trying to improve it without a specific goal and a business purpose in mind is not.
The big question is how well is the program currently running meeting the needs of those that use it? While it may not be the best looking code, it does work which may mean that you end up doing 101 refactoring exercises around it to get enough of the basics down to make other changes.
While you may be able to ask the original writers of the program, this can be a possible sore spot if they think it is awesome and you think it is crap, for example. It is an idea and one that should be carefully analyzed a bit before one goes and ends up burning bridges because they think you can't appreciate their genius in what was done.
Often this aren't done in an optimal way and so as one learns better ways to do things, things are done in better ways. There is a limit to that of course, but I'd start with the idea that you have some refactoring lessons to help get the basics of the app under your belt and then start putting in enhancements and other stuff to see what was really done in the end.
Related
so I got a budget to clean up code that I've inherited from another programmer. the code is in really bad shape, there's lots of files not being used, there's lots of functions not being used. It actually looks like linear programming instead of object oriented. My issue is whether or not I should
a) Clean the code, restructure it, and try to delete all unused resources
b) start with a fresh framework (it's using codeigniter), and copy over the files that are needed to run
I like option b because it kind of reminds me of a new laptop from best buy. I can either spend the time removing all the bloatware or do a wipeout and create the system from scratch, which I always do. The only problem is that this time, there's a lot more involved then just creating a fresh system. Here are the pros and cons:
PROS
Clean system that is very easy to maintain
Don't need to go around searching for unused files
Easier to keep track of what I've done
CONS
Lots of things can break
Might miss required files
Might take longer
What do you think? Can you give me some of your pros and cons, and what you might do in a situation like this?
Update
A lot of people say that I am missing an important part, budget (time and money). We do have a decent budget, but my project manager is willing to go over if it ensures a more solid system with quicker turnaround time for new features. It's hard for me to quantify budget because you have not seen code, so giving hours won't help which is why I did not say anything about budget. I guess from your prospective, consider this a budget that can accommodate both solutions.
Often a hybrid approach works better. Keep the gold nuggets and toss the rest. Most likely there is some really effective code even in the worst project. Also, things that would be painful to rewrite and already work well, you might just clean those up a little.
It takes a little judgment to determine what to keep, but you can kind of have the best of both that way.
Cleaning someone else's code can be a nightmare. If you can actually choose and the stakeholders agree, I'd strongly recommend you to start over.
I had an experience like this last year and to this date, the software is still in pretty bad shape, it's almost impossible to track every mistake made by the programmers we inherited the code from and spend a LOT of time on support for hidden bugs and stuff.
I guess it somewhat depends on your time constraints and how intimately you'll need to know the project.
I just finished restructuring some code written by a math-majoring grad student. Bright guy, but he's not a programmer and the code was, as you said, very linear. Long story short, I rewrote about 90% of the code and took more time doing it than I would have liked. It would have been faster for me to start from scratch, using his code as a reference. Not only that, if I had planned on making as many changes as I had, I would have put more thought into the restructuring process. On the bright side, I now know all the code and concepts in this project very well.
On the other hand, if you don't plan on making many changes or having to maintain the code, maybe it's not worth the hassle. Get it to a usable state and tuck in back under the rug, so to speak.
My 2 cents...
This question reminds me of Joel's article I've read a while back.
The single worst strategic mistake
that any software company can make:
They decided to rewrite the code from
scratch... It’s harder to read code than
to write it.
http://www.joelonsoftware.com/articles/fog0000000069.html
This is my first time posting something like this. I'm a complete n00b at programming/php. I was trying to grasp all the tutorials out there and wanted to create a sort of framework to base projects off of for web db/applications. I came up with a few files for crud operations that I know must really be horrible code. I was wondering if I could get some advice in advancing this 'framework' to the next level. I'm not great at OO, but I understand the concepts, so I went more functional instead. I'm aware that the songs are gross, I don't need help recognizing that.
I would like some help on the database calls. I understand I should be using PDO (to help with injection), but I'm not sure how to convert this code to that structure. I also realize that at the least I should be using mysqli functions. Again, n00b.
I am also aware of validating and sanitizing data, but again, being so new to this, I don't know where to begin. Especially if I wish to keep it tight and small. The comments are funny from a programmers aspect, but hey, you work with what you got. I'm trying to grasp MVC and be able to tie in AJAX and templates/skins, but the crux of it is to work with databases.
I do like how there is one config file that works with all the other files, and how that results in small files for index, read and delete. The others get a little longer. Not that including files is makes me cool or anything.
I think I fail horribly at understanding MVC and structuring the project so that maintaining it and adapting it is easier. I also realize that there is a lot of html in those php files which is a no-no too. How do I fill in the gaps from what I do know (I know what every line of every file is doing) to what I should know.
The code can be found here (probably not sourceforge worthy, but I want to help others learn as I do).
https://sourceforge.net/projects/eleete/files/
Building such a thing takes a good amount of time, before you go doing so I would suggest looking into open source CMSs such as Wordpress to see if they would suit you better than putting in hours of work creating something yourself, the reason I say this is because to begin with you may think it won't be too hard to create one for yourself, but as you get into it you will realize there are many avenues that need to be explored in terms of security and features.
However, if you still want to build something the most important thing is to be creating reusable, and easily understandable code. For example if you want to create db entries for things like pages, you'll want to create functions to do so, to which you can pass variables such as titles etc. A good way to begin is to create functions for collecting data from your db, for example siteinfo() could be a function that returns an array full of site info. To make sure every file has access to such functions you will need a global file like functions.php for example which you will need to include in each of your other files.
Remember, building a framework is hard work, but if you do it properly and thouraghly you should increase your productivity a good amount - this is something you need to consider when building it, make sure you're not doing things in a roundabout way. Make it simple, make it reusable, and make it powerful.
First off, welcome to the community! I hope you find here people who are excited to bring your more into the programming fold. It's an exciting place to be.
I get the impression you're biting off quite a bit. I fear you're also under the assumption you can write the perfect program from the get-go, which is a flat-out myth no matter how long you've been in the industry.
As to the former observation, my recommendation would be to pick a simple problem and try to solve it. My favorite recommendation here are simple card games - blackjack, for instance. Dice games like craps also make for short, achievable, and interesting programs. The intent of these projects will be not to build a code framework as much as your skills in dissecting problems and turning them into a solution the computer can understand and solve for you- your code.
Starting small will keep you from getting overwhelmed early. Starting fun will keep you motivated through the inevitable snags that will tempt you to throw your computer out of a closed window.
All that said, we're still here to help! Specific questions to specific problems tend to get the best feedback here, as well as questions that demonstrate you've done at least some homework on your own in terms of trying to solve it. The Stack Overflow community will be happy to give you a hand up, but not a handout. Good luck!
You're going to be much better off using a clean, simple framework. As you're so new with this stuff, I'd recommend CodeIgniter for sheer simplicity and speed. It helps enforce the MVC framework you're not totally familiar with yet, has all the built-ins you're likely looking for, and has a decent community. Being a Zend guy, I should probably suggest that, but it's definitely not the easiest to get started with.
MVC and OO are concepts you really should learn well out of the gate before going forward. This tutorial rocks. There are dozens of MVC primers out there, but in essence it boils down to separating your data layer, view layer, and the like.
PDO is not necessary to be safe, you just need to escape your sql with Mysql_escape_string or the like. I'm actually not a fan of PDO due to the monkey wrenches it throws into debugging.
Since you're new, I'd also recommend Xdebug on your server for troubleshooting. It cuts down debug time immensely.
In my experience, unless you've had to fix the shortfalls in someone else's attempt at a framework, you won't really understand how to build one yourself.
One of the key qualities of any sort of API or framework is the concept of abstraction. In a nutshell, as you find yourself repeating code, look for where the repetition could be abstracted away. The trick about this when you're building a framework is to do it in an extensible, usable fashion so that you have pieces that build on each other. In other words, abstractions can hide other abstractions. For example, It's all very well to abstract away the job of assembling an SQL UPDATE statement from a list of fields, but why does the application page have to check the list of fields is correct? Put that behind another layer that can be taught what the valid fields are for a certain object.
Another key quality that comes up at this point is refactoring. The phrase "be prepared to throw the first one away" is sometimes bandied about in programming circles. What it really means is that you should always be open to the idea of re-writing code because you've thought of a better way to do it. Even if you have to rebuild the code that calls it.
I have recently began working as a developer and working under a more senior developer who is kind of supervising / mentoring me.
A lot of things that he is advising just dont seem right though. For example, he tells me to just write my code in a procedural way ignoring how well its written or its overall design and just get it to work. Then iteratively it will get better as it needs to, improving the code over time.
This is making me uncomfortable about spending time actually properly thinking about the solutions and indeed the actual problems before coding and I feel that by rushing in and coding this way that in the end, more time will be spent on this. Unfortunately i am not at the stage of being able to solve problems immediately by writing perfect code first time.
Also,m he frowns upon documenting code, beliveing that it should speak for itself. He feels that a short comment at the top of each method should suffice. Again this seems counter intuitive to me.
All in all, i feel that i am now writing really hacky code in order to just get somehting up and running. Is he correct and is this the way things are done throughout the industry?
I'm gonna go out on a limb here and suggest that you might be misinterpreting what the senior dev is telling you. "Just make it work" and "code should speak for itself" are mutually exclusive. If we assume this guy does really know what he's doing, let me offer a couple of alternative explanations:
It's easy for new developers to get lost in the weeds agonizing over The Right Way to design software. It's a kind of Analysis Paralysis. He probably wants you to dive right into code quickly so that you actually get something written and you quickly discover what doesn't work well. It sounds like he's letting you fail early and often in order to learn.
A lot of new developers liberally sprinkle their code with useless comments. He's asking you to write self-documenting code, not hacky and confusing code. If you're only allowed a short comment at the top of a function, you have to use clear variable names and simple straightforward algorithms for the code to make sense. This is a Good Thing.
There's nothing wrong with sitting down with your mentor to clarify what he's telling you. You do have valid concerns. Don't hesitate to ask him for more information. It shows confidence and an ability to think for yourself. Good employees aren't mind-numbed robots.
No, that's not really how things are usually done. But there are some considerations.
There's a development pattern called "test-driven development". In this pattern, you basically write the least code possible in order to pass whatever tests you have. As the requirements change, you write new tests and then change the code to match. He could be angling you towards something more like this. In which case, if you write good enough tests, it doesn't matter what the original code looks like, if you tested for every case you needed to, then the code will always do what you want even if it is a horrible mess. (This is, by the way, why some people don't like test driven development).
On the subject of comments, of course comments are important. But comments are not a substitute for easily readable code, with properly named variables and function names. Over commenting is definitely possible and makes code harder to read and understand (because every other line is a comment like // increment i). Also, the more comments you have and the larger they are the more likely they are got become outdated and out of sync with the actual code. Everyone is going to read that and say "that won't happen" but it always does. Someone always comes in to change "on little thing" and doesn't update the comment, and then after that happens about three times the comment is just plain wrong.
There is one more thing to consider. Consider the possibility this person doesn't carry what he's told you as a philosophy, but rather he's just trying to help you. Maybe you've spent too long trying to properly design your solution before writing anything and he feels if you got something down on "paper" first it would be easier for you to improve it than trying to hold the whole solution in your head. Maybe you've been writing too many comments, bad comments, or spending too much time on comments (or even on comment formatting, I've seen this happen) and he feels you'd learned more at this stage by spending time on your code than on making pretty comments.
There are many schools of thought and many different styles. I have stopped counting and instead try to use a pragmatic approach.
In terms of implementing code I use the principle "make it work", "make it right", "make it fast". But then I also use "The simplest thing that could possibly work" (DTSTTCPW)
How much comments you write depends on a number of factors. One school of thought indeed advocates the thesis that good code is self-documenting. Also, I have seen endless comments that were completely out of sync with the code.
Another school of thought believes that you need comments.
I'm taking the position that there are several factors that influence your choice. One is your personal preference. Then there is your boss. In other cases there is your team. Ideally you would be all on the same page by jointly agreeing on coding standards. And in the end if you always have the choice: Love it, change it, or leave it. Choices 1 and 3 may be the only ones if your boss (or mentor) cannot be convinced or isn't willing to find consensus in the team.
My understanding of iterative development is that you add features in small increments. At any given time you are ready to ship and your code is as lean and mean as you can get it, including comments where appropriate.
My understanding of test-driven development (TDD) is that you use tests to drive the design of your system. This is more and beyond mere test-first programming.
This approach has worked for me for the last 10+ years and with many teams I have worked with. But I am sure that there are many other options, styles, preferences, methodologies that work equally well. It all depends!
Also, he frowns upon documenting code,
beliveing that it should speak for
itself.
That's pretty much all I needed to read. This person really has no clue about what it takes to write maintainable code.
With that said, this person is obviously your mentor/supervisor, so you can't just say, "hey, that's stupid", you have to do it tactfully.
But not documenting code because it "should speak for itself" is a recipe for disaster. And you should definitely pay attention to writing clear, effective and efficient code. It's always better to do something right than to just hack something together that you're not going to understand 6 months from now. If you don't understand it, chances are no one else will either.
I think you should talk to their supervisor and explain the situation.
With that said, there are sometimes reasons to take shortcuts if the timeline is tight, quoting Jamie Jawinski, who worked on Netscape,
"We're going to ship the
highest-quality product we can on
March 31st"
So you have to find the balance. But overall, writing helpful comments in code doesn't take that much more time, certainly not enough to significantly affect a project timeline, and I like what Donald Knuth said:
...when you write a program, think of
it primarily as a work of literature.
You're trying to write something that
human beings are going to read. Don't
think of it primarily as something a
computer is going to follow. The more
effective you are at making your
program readable, the more effective
it's going to be: You'll understand it
today, you'll understand it next week,
and your successors who are going to
maintain and modify it will understand
it.
In short, there's no substitute for writing highly effective, clear, and maintainable code, even with a tight timeline.
Its 100% opinion here, but if your solution is well designed I think a comment for each method can be the right amount. You should be describing what it does and why, but not going into the details of how. Unless your method is extremely long (indicative of poor design), the code should explain itself i.e. if your method looks convoluted and is hard to understand, perhaps you should break it down so that it reads more naturally. There are always exceptions, but thats my opinion.
Where I work, the code seems to have very few comments but if the method name is truly representative of its function, and the code inside the method is clean, I have no problems understanding it.
Unfortunately i am not at the stage of
being able to solve problems
immediately by writing perfect code
first time.
There is no such thing as a perfect code, its about knowing which comproises are acceptable.
Perhaps your metor is just trying to make your life easy by saying 'don't worry about the design'.
Or maybe he is referring to the practice of red, green, refactor (Test-Driven Development) - the idea that you should first write tests, then write the code to the point that it works - only then do you refactor it.
I agree on self-documenting code to a degree. You should name your variables and methods well rather than relying on comments. e.g. which would you prefer?
//Get the speed of the train from the database
int value = GetValue();
int trainSpeed = GetTrainSpeedFromDatabase();
What if I decided I wanted to get the trainspeed from an XML file now, in the second example I'm much more likely to update it so it makes sense and not leave the misleading comment.
I have been tasked with supporting and maintaining several PHP/MySQL web apps (I use the term 'app' lossely) that seem to defy every known coding standard.
The PHP code contains routines, procedures, business logic, and even queries - it's all in the code. There is no object-orientated programming, not even MVC, and certainly no separation of the presentation layer from the application layer. No framework was used to build these apps either and I am using the Yii Framework for new projects.
Although it's time consuming should I rewrite these applications? At least half my week involves fixing them, doing updates are having to work with these existing apps in my new work.
Anyone have any advice on this?
An age old question that is asked alot.
When do you refactor code?
How do you refactor?
How do you stop yourself from refactoring working but awful code?
Basically, if it's working dont' break it. If you work in it, and can make changes to clean up the code without breaking it then do it. Rewrite code? I'd go with the idea of, What's the return of investment, how much time would it take, can you dodge the bugs of the old version without introducing new ones. Things like that.
Good luck with your project, and hope this helps.
I would caution against an all-out rewrite. If the application is working and has users, the path forward is to modify the existing codebase.
Yes, you can implement a framework into an existing framework-less codebase. It takes a lot of effort, but it is possible (I've done this several times). Starting over will cause you to lose precious time. That's been proven time and time again (remember Netscape?)
You're obviously smart enough to know that there is a problem, and to know that the solution is to improve the applications by implementing frameworks and clean them up. That puts you ahead of the game.
Implement new frameworks in phases. Start with an MVC framework - get it into the codebase, but don't fret about the fact that there is no separation of layers yet. Get a new version out that's built on top of an MVC framework but isn't truly obeying MVC conventions. It's a start. Then take a next step - move the business logic into the model layer. Or maybe leave it as it is, but make it OO.
Remember, your job is to produce a product that users can use. Your job is not to adhere to best practices. Meaning - yes, best practices ARE the correct course of action. But they don't matter squat if users can't use your app or your app can't compete with the competition. Don't lose sight of that. Work to improve the app so that you can turn it into a great product, but don't let perfection be the enemy of good.
In my experiences, this has typically been a business decision. Do your bosses know how much time you spend maintaining these systems? How many users actually use these systems? How critical are they to the business? Can you sell management on a rewrite and can you prove it will be useful and beneficial?
You can start some basic refactoring already in your day-to-day maintenance. Whenever you need to make updates, even if it might take a little extra time, find a way to work an OOP solution of some sort in, or clean up the code that's there to make it easier to handle. All-out rewrites are typically not a good idea and are a hard sell, but if you're already maintaining and adding in new functionality, there's no reason you can't use the new code or fixes to improve what's already there.
Will the products last for a long period of time? Will other users see the code and think that you did it? If yes to these, then you might as well rewrite the code. Try and get some support from your company and let them know the benefits and maybe you'll even get noticed for it.
While having no separation between the presentation layer and bussiness layer is clearly bad, there are some merits with other choices. If it is a pain to maintain code, just refactor the code as you go. Since you are familiar with good design patterns, you should be able do it fairly easily. Moreover, this will also help you reduce the bugs in your code. But remember that while refactoring code, things get worse before they get better. So, don't give up too soon.
I would suggest it depends on how much is the user load on these apps, do they really break apart in live scenarios and how much time are you wasting daily on these fixings and all.
Its always better to rewrite than break head on something which is totally messy.
My understanding is that asking for a work sample is a good way to determine if someone has the skillset you are looking for, as some people just interview well. So I want to ask potential developers to write some sample code for me.
I'm looking for ideas on what kind of small project would be something they could do in an hour or two, and would show that they have a good grasp of OOP, good coding practices, etc. And what to look for once they finish - how to evaluate it fairly and usefully.
For context, I'm a small business owner, interviewing prospective developers, for PHP development on internal projects. I can code PHP but am not an expert (some of the work is refactoring code I've written to be better structured and consistent), and so I'm also looking for what to look for when evaluating the samples, given that I'm not a trained or super experienced programmer.
Especially for people who have done hiring of this type before and used this method.
I was also thinking I could give them some code to refactor, and see how they do on it. Has anyone ever given a refactoring test as part of the hiring process?
Clarification:
I'm not talking about coding during an interview. I'm talking about coding instead of an interview. For context the inspiration for this question came from this article in FastCompany about how work samples are better predictors of job success than interviews:
Why It May Be Wiser To Hire People Without Meeting Them
http://www.fastcompany.com/magazine/136/made-to-stick-hold-the-interview.html
I would create a not necessarily good application and embed some bugs. I would come up with some simple functionality to be added to the program.
Does the applicant find some bugs?
How does the applicant's code integrate into the existing code?
Does the applicant get stuck on something that doesn't really matter?
Does the applicant adapt to the coding standard of the existing code?
After this exercise, discuss the code with the applicant. This may be more valuable than the actual code.
NOTE: with regards to #bpapa answer I would make sure that problem is novel and obviously not to be used in production.
Personally I would refuse to do this when asked. An interview is one thing, and doing programming questions on paper to asses technical knowledge is fine, but actually writing some kind of application for somebody is billable and I wouldn't do it for free. Even if it only is supposed to take an hour.
I think you should focus more on what the person has done in the past, and ask technical questions that you know the answers to (since you said you have limited PHP knowledge and want a PHP developer).
I would heed Joel's advice that giving homework assignments for interviews just weeds out the best programmers (paraphrased from his book). The better programmers have a lot of options and so won't want to go through the exercise of a programming assignment. They just won't apply. That will leave you with the mid-competency people. Unfortunately, in my experience those are the ones most likely to try to look better than they are and if you aren't an expert yourself, the ones most likely to mislead you.
Here's an alternate option. Have them point you at some work they have already done. Not necessarily the code, but the site. During the interview, ask them questions about how they coded it. What data structures did they use? How were the classes or functions organized? What problems did they have to overcome?
Then as traditional programming questions in the interview that they could answer for you ont he spot. This way you can gauge their understanding and their syntax. The two don't have to be the same question.
If you are not an expert then I would suggest you be careful about trying to evaluate other developers. You should probably figure out a better way to assess the dev skills of someone else if you are not that comfortable with your own level.
I am not sure there is a good solution for you.
I'd make the coding samples very straightforward and not have it take an hour or two. Simple coding exercises that take a few minutes should be sufficient - combined with other discussions about best practices, frameworks, design questions, etc.
I like the problems at streamtech. They are pretty easy and can often be done in rather short time, but they show that the applicant is capable of structured thinking and translating this to structured code.
As for evaluation---I would use this as an opportunity to learn. Do the problem yourself first, then compare to the applicant's code. Look up any constructs that you don't know, then ask yourself which version is more obviously correct.
I think the best thing you can do is try to have a real expert sit in on the interview with you. Hire a third party if you need to. I'm not sure it's possible to be able to give a quality assessment of someone who is a more experienced developer than yourself.
The other thing to consider is that really good developers may pick up on the fact that they are more experienced than yourself, and if you indicate that you are one of the developers it may actually put them off (not trying to be offensive, I just mean in the context of you implying that you are not very experienced.)
Give them an address or such as a plain text file and ask them to create a simple script to turn it into XML. I used that once and it worked wonders.
If you want to test them on the spot, ask them to reverse a string. From an organisational standpoint, perseverance, determination and enthusiasm are just as important as being technically adept, IMHO.
Well, everyone seems to be discouraging the coding effort for an interveiw. I'll disagree with the disagreers. To answer your question--if you want an example of what to have them code--drop a simple calculator on the table in front of them and ask them to write a program to create the calculator virtually. Give them half and hour and see how far they get. Some may finish in that time.
Have you ever tried pair programming before? Two people sit down at one machine, they share keyboard and mouse, and talk about what they're doing as they go. I think this is absolutely the best approach, because it will, eventually (after everyone's panic subsides), really indicate how well you two work together.
If you're not a great programmer, this person should be able to teach you and put you at ease. If they're not that good, but you work together well, that might be more desirable than a brilliant but unpleasant person.
At the end of the session, just delete your work. No big deal.
I've never been a part of the hiring process... but in interviews I've done, I was asked once to implement a doubly linked list, and another to work out an algorithm, the classic, how many integer points within a given shape, in this case three points forming a triangle, once in O(n^2) and then again in O(n).
I don't think the way to do it is to make them program something, but to make sure they know how to figure it out. You give them a problem or ask them a question, and tell them to think out loud, and observe their thought process. This doesn't exactly show if they have clean code, but depending on the problem it gives you insight as to wether or not they know what their talking about.
Having a small, well defined task can help you take examine people on a level playing field with a relatively small investment of time on their part. You don't need something complicated to see what people can do.
In the past, I've asked people to write a small web application that exercises a few fundamental concepts. We keep the particulars of what the application is supposed to do really simple.
I would also try to avoid tasks that require a lot of supplemental knowledge (viz, don't ask them to solve a problem from your particular problem domain).
Edit:
Regarding "small, well defined tasks": What I try to shoot for is something that includes a very thorough description of some simple business logic as part of a larger programming task. For example, one of the programming assignments I've given in the past involves setting up a simple Java web application and implementing a few features. We made sure to describe thoroughly how the features were supposed to work to remove ambiguity. This was for a couple reasons:
The point is really to see if the candidate can build a simple application from scratch, not to see whether they can guess correctly about what we want.
If you define the task really well, you get to see more about how thorough someone is with the type of work that they're likely to be doing in a business situation.
We wanted something flexible enough to give to candidates at varying levels of experience.
I should note here that I think programming assignments are most effectively used to check for competency. If you give a really hard assignment, or one that isn't well-defined, odds are that you're not going to get results that tell you what you want to know (unless you're testing specifically for how the candidate handles difficult assignments or ambiguity).
I argree with bpapa about it being an interview instead of a test run, maybe instead consider asking some questions about how they would undergo certain talks to do with the programming...
I once had to sit a Visual Basic MCP exam at the end of which they didn't even bother to give me the result.
Happily though when I asked the question as to whether I would be given the result I was sitting at the Commit/Cancel screen.
So I hit cancel thanked them for wasting my time and walked out.
To answer the question:
For PHP, I think a shopping cart, address book and forum would be good projects. Those usually cover a wide spectrum of web-programming topics - sessions, registration, database, form processing and authentication.
Personally speaking:
It looks like you looking more of an architecture person than a coding guru. I wouldn't penalize the applicant because he cannot come up with the name of an obscure function or need to refer elsewhere. The key thing is that he has the initiative and know where to look (heaven knows how many times I need to look up PHP.NET). A good question for an architecture guy, IMHO, is to tell him you have a data-set, but you have three different ways of displaying them and each view has different operations. If his answer is just a gigantic SWITCH-CASE, then he may be the wrong choice.
Usually weak programmers does not understand recursion pretty well, that's from my observations as far as now, now this does not have anything to do with PHP directly and probably a recursive factorial or fibonacci series wouldn't be a big deal, but let's say to load a tree control with data from a database with some parent-child relationship might be a good sample.
Also as you're not an expert as you said, think off something you can handle confidently.
It usually depends on the language you are hiring for. For example, when I went and gave an interview for PHP, I was asked to write a blog script, using custom MVC framework, whereas when I interviewed for an opening as a JS dev, I was asked to code a certain plugin in jQuery. Its more dependent on you are hiring the guy for ultimately. You dont want to ask someone to write you a music recommendation engine and then have him work on a payments gateway processor.