Strategies to document + comment retroactively - php

I'm just about to finish a marathon 9 month project-- a web app with over 70k lines of code. Problem is I hardly used comments, never used javadoc, and never kept any good documentation of any kind. (oh the guilt!! :) )
I now need to focus on the non-technical aspects of my business and pass this giant off to a programming team for maintenance and new features. So what can I do...what are the most useful comments/documentation to write? What's the best strategy for retroactive documentation? (Are there books on the subject?)
PS. Thanks for your months and months of help Stack Overflow. I barely knew HTML a year ago. You got me through it all!

70K lines isn't all that large. It might be larger than projects you typically work on, but at least it's not so large that one person can't understand most of it. That's probably what got you into trouble in the first place. It wouldn't kill you to go through each file and write a few sentences about what the class does.
70K lines is way too large to foist upon someone, or some team, without some sort of explanation of what it does and why. Take pity on your poor underlings (and reduce the man-hours that they'll waste scratching their poor heads) by at least writing a road map that explains in detail what the project does, how it's organized, which parts are important for performance or to meet requirements, which parts need work. If you had any written requirements for the project, those should be included.
I'd imagine that before you make your team work on this undocumented pile of code you plan to at least sit down wit the team members for a day and give them an orientation. Write down everything you'd want to tell them during that orientation. Give the team that document and some time to read it before you really do meet with them. Now you can use that day with them to refine the document by answering their questions. Ensure that the answers make it into the next revision of the document. Let your team's first task be to fix the problem you created. That'll help them get ready for the time when they do start implementing new features.
Be available to answer questions from the team for the forseeable future. Create some sort of system for organizing and preserving the information you provide. A wiki seems obvious, but you also want to make sure that new questions get noticed and answered quickly. A defect tracking system could work well. So could some sort of Q&A format like SO.
Change your attitude toward documentation. Learn from your mistake, change your ways, and encourage/insist on people spending time to document what they do. Try to make documentation as automatic as possible by connecting your defect tracking system and your version control system. Give your people the resources they need to produce useful documentation. Put someone in charge of documentation.

I tend to do just as you do, retroactively comment, if I comment at all. However, when I do, I try to document mainly my custom functions & classes, and important parts of my code. I note things such as:
Required Parameters
Return values
Explanation of the function
The best thing to do when commenting is think about what'd happen if you suddenly disappeared and couldn't explain your code. What would the developer who took over need to know and understand. Obviously, you shouldn't have made your code too abstract either (aka, only using variable names such as $x, $y, $z unless appropriate).

Related

Designing/Visualizing a Mysql database to avoid rework

I have been coding php enterprise applications from many years but still i would like to take a feedback.
Usually when i get the functional specifications, i create a worksheet of how long it will take to finish the project. I don't have a team and i code start to end.
Almost in most of the big applications after reaching the midway, i figure out that the database should have been designed slightly in a different way. So i create or delete or modify few tables (sometimes more than few tables) for better optimization and data fetching.
So in my experience, i always have to do a rework somewhere in the mid way.
Below are the steps i follow for big applications.
Visualize the database. I prefer sketching them.
I have coded my own PHP MVC Framework and i use that.
Create unit tests (if required)
Do some optimization.
Code cleaning.
Deliver.
My question:
I was never taught programming. I learnt everything through mistakes and experiences and ofcourse Stackoverflow. Am i following the right pattern ? Or is there a better approach to avoid rework. I am sorry, my question might sound noobish, but i am seriously looking for some helpful advice.
This ended up waaay too long for a comment...
Take StackOverflow with a grain of salt. Yes, there are some very smart, well-written answers, however there are also many cases of 'blind leading the blind'. You generally don't ask a question on SO if you know the answer, and if someone gets a terrible solution to their problem, but it works and they don't know any better, they can mark it as accepted like anyone else. There are a lot of people on this site in the mindset "if it's accepted, then it must be correct" and that will bite them in the ass eventually.
Find someone in your field that you personally respect and ask them to look over your DB design/methodology in detail rather than posing vague questions on SO. Your process sounds just fine in the broad strokes you've outlined, but who knows what kinds of devils are hiding in the details.
If there are certain small portions of code you'd still like to be reviewed by internet strangers you can try CodeReview.StackExchange.com. CR questions on SO get closed faster than you can blink.
I think your steps are good. You may consider posting some of your working code for review to get experienced programmers' opinions on design, best practices, etc. There are also chat rooms with lots of active users who are specialists in specific languages, if you don't have an expert on hand.

What is a good, well-organized web development workflow from start (planning) to finish (testing and production)? [closed]

As it currently stands, this question is not a good fit for our Q&A format. We expect answers to be supported by facts, references, or expertise, but this question will likely solicit debate, arguments, polling, or extended discussion. If you feel that this question can be improved and possibly reopened, visit the help center for guidance.
Closed 10 years ago.
I've been a PHP/MySQL developer for a number of years now, but unfortunately have only worked with small projects up until now. I'm starting a new website now that is very complex and I'm starting to get confused with the workflow. I'm not sure which parts to take care of first, as they're all fairly intertwined.
I'd love to know how some of you manage your workflow for a new website. I'm working independently, so it'd be easier to explain without multiple developers involved. Also, I'll be using the CodeIgniter framework, so it'd be great to have the workflow involve the MVC model, which should actually make the workflow easier.
After some searching, I came across this helpful diagram:
However, I'm not too sure what falls into each category. Here is a general rundown of what I understand so far. Please feel free to correct me when I'm wrong or when there is a better option.
Planning
Make sure you have clear goals for the project: What do you offer, and for whom? How will it be helpful for others? Etc
Sitemap
List all the pages and sub-pages that are going to be on the site.
Wireframes
Go through your whole sitemap and make a rough sketch of every single page. (How detailed should you get?) You can use pencil and paper, or programs like Axure or Mockingbird.
The next major category in the workflow chart is content, but I'm not sure what this involves. Is it all the text on the website? Database structure? Something else?
Artwork
The actual design/template of the website. Is this really the right place for this, though? I would think that the coding and functionality is more important, and make the design after that.
Coding
This step seems to all-encompassing, and I'd think it needs to be broken down. Is the database structure made first (or was that done in content, after the wireframes?) Do I make the outline for all the functions for each page in the sitemap? Do I just create all the necessary controllers and make comments of which functions I'm going to put and where? Do the models go after the controller outlines, or vice versa? When do I start filling in all the controllers and models?
Constant testing is involved to make sure your code works properly.
Content Population
Would this include the view files in the MVC framework? In other words, all the data that the controllers and models provided?
Final Testing
Make sure everything works in all browsers. Making tweaks and changes here and there. Go all out with numerous "what if" cases.
Production
Site goes live.
Conclusion
The above is what I understand to be an organized flowchart of the steps in developing a complex website, but my understanding could be greatly improved. What should be changed? I could use all the suggestions possible. Thank you.
EDIT: Someone here mentioned "agile development"--from what I'm reading thus far, it doesn't actually have a structure. Correct me if I'm wrong. As I commented on that answer, is it really possible to develop in such a way for complex sites, such as Amazon or Ebay? The workflow process, in my un-knowledgable opinion, should have a clear plan, or else there would be no focus in the project.
FINAL EDIT: Although this question was closed, I'd like to add some info for those that may find this later. I found the following workflow useful: http://www.webassist.com/free-downloads/tutorials-and-training/web-dev-workflow.php. A PDF of the general workflow: http://assets.webassist.com/how-tos/Short-Dev-Checklist.pdf. Agile development can also be used of course, but this could be a good starting point for those that don't know where to start. I may add additional workflows and examples here as I find them.
The R&D world is moving towards agile development, where you don't do so much planning and write everything down from start to finish, but rather do small iterations and make small changes so that you always have one clear goal in front of you, and you can adjust your direction as your understanding of the requirements improves (real ones, based on user feedback, not estimated guess work based on what you think the customers will want/use)
I suggest you research Agile development, and Lean startup methodologies, it changed the way I build online services, and will make you much more efficient and productive.
I can tell you that my online service went live about 2 days after I started coding. That does not mean that you open it to real users right from the beginning, but you can get immediate feedback from the real world instead of keeping it all on your dev machine until you're "ready to go live".
Agile development is definitely a good idea for websites (as, typically, the coding is both relatively easy and independent). The main point about agile is that it allows for changes, and it also allows for adjusting for "it took longer than expected to do Feature B, so C and D will be delivered in another iteration". As you are probably aware, planning larger projects can take a lot of effort, and is almost always longer than you'd expect. With agile, you do each bit as a "vertical slice" - meaning anything done should contribute something useful to the product, all the way from adding a ling on the front-page [or wherever it belongs] to adding the code to handle it and the database model to store/retrieve relevant data.
I'm pretty sure that you still need to do a fair bit of planning for a large site with lots of pages, and lots of database tables, etc. But as long as you have a reasonable grounding in general website/database design, Agile methods will let you design "walking skeleton" (somethig that works in the basic concept, but need more meat on the bones to be a working product). Then you flesh out the sketch with more features, each feature is "complete" in itself, and adds something the customer needs. That way, you always have something you can deliver to the customer after each workitem is finished.
I'm also convinced that Amazon or Ebay has A LOT more than 20-30 tables. I work with a site called www.planetcatfish.com, and it is MUCH smaller and simpler than Amazon or Ebay, and it has 25 tables (besides the phpbb tables for the forum, which is also used for the site specific user functionality). And that was written over many years, using mainly php, a little javascript and a fair bit of mysql inside the php code.
TheZuck's answer is good and very helpfull so I'll just add some of my own experiences, which doesn't necessarilly mean that you'll go through the same thing, and probably won't if you have half a mind for business (which is what I'm lacking. :S).
Content has always been a problem with my clients, so I'd say get them working on that early! If you're working with a copywriter I guess thats not a problem. But there should be some sort of penalty for not delivering the content to you in time.
It is also worth noting that your clients will only really start thinking about their website once they start thinking about the content. Expect to hear about them wanting some changes when they've started working on it.
If you're clients are small businesses, then they tend to not understand what it is that actually takes time. Even though agile development is really nice I believe that this will be hard to implement towards small businesses since they don't have very much money to work with and will probably want a fixed priced for a finished product. And if it's fixed they'll just get pissed if they've used up all their time or whatever it is that they've paid for without giving them a finished product (working deliverable, is not the same as a finished product!).
Clients tend to be IT-illiterate, sometimes to the extreme. Count on you having to put some or quite a lot of time into explaining "obvious" things to them.
Don't overestimate yourself and your abilities, since this will probably mean that you'll charge less than what is actually reasonable. A quality website should cost money, but I for one will understand if you charge to little, you know just to get a few clients.
I realise that this isn't really an answer to your question but I hope it will help somewhat.

True meaning of iterative development and refactoring code

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.

Is this interview question too hard for a php dev. job? [closed]

As it currently stands, this question is not a good fit for our Q&A format. We expect answers to be supported by facts, references, or expertise, but this question will likely solicit debate, arguments, polling, or extended discussion. If you feel that this question can be improved and possibly reopened, visit the help center for guidance.
Closed 11 years ago.
We're looking for someone to help us enhance & maintain our high-quality, php-based prototype of a transactional web app. Ideally, who can communicate well, and do both front- and back-end web development (as well as smart/gets things done, etc.). Among other more general things, I've been using this question:
Given this:
$foo = array(1, 3, 7);
write a function (on this whiteboard) to sum the values of the array.
It seems trivially easy to me, but has caused a couple of deer-in-the-headlights situations, which always makes me feel like a villain.
I've read a number of posts here and there (including both Joel's and Jeff's) saying that how candidates think, design skills, passion, etc. are more important than any specific technical skill, and I agree with that. Also, I can see that programming at a whiteboard is a little unrealistic. OTOH, this seems so basic to me that I'm inclined to see it as a fine first-pass filter between front-end devs (who know their way around html, css, and how to copy-and-paste a js function or two), and people who can really code. Thoughts?
A touch more info: I'm open to all sorts of answers: array_sum, a for loop, a foreach loop. Heck, if they want to write an ArraySum class, that would be overkill, but just fine. Using javascript, or another language would be fine, if they're more comfortable with that. Even attempts with minor errors would be ok, but I've had a couple of complete freezes, so I just wanted to sanity check myself.
I would consider that much too easy of a question, personally. If someone asked me that question in an interview I'd probably be busy trying to figure out what the "trick" was, because it's so simple.
I think it's fine for weeding out the absolute worst programmers, but make sure that you don't have one particular "right" answer in mind and refuse to accept anything else. For example, don't only accept "use the array_sum() function" as the correct answer, where it's really just a test to see if they know the function exists.
I mention this because my fiancee once had a programming interview where she was asked how she would reverse a string. She gave several different algorithms that would accomplish it, with the interviewer telling her that she was wrong after each one. She finally gave up, and he (disapprovingly) told her that she should have just used the String.Reverse() function.
Don't do that. Please.
in my opinion, the question is perfectly valid, and tells a bit (not a lot, but an important bit) about the candidate, depending on how much time you invest in it. just tell her that it's not a trick question beforehand, that it's really, really as simple as it appears, so she doesn't spend to much time thinking about the pitfalls and to minimize the deer-situation. throw in you do that just as a measure to filter out the people who apply for a programming without actually knowing anything about it but hoping they get hired anyway by pure luck (if they know how to code but are just nervous, that should take a bit of pressure away). let them code, but don't focus if there is a $ missing or if the <?php tags are present or not.
if she provides array_sum or sum_array as an answer almost doesn't matter, especially if the language in question is php (but if two candidates are equal otherwise ... i can't even remember the last time i had to use this function). and the use of an auto-completion and syntax-coloring (with predefined keywords) IDE vs. a dumb text editor matters a lot in this hindsight. in this case ask for an alternate, handcrafted solution.
if i was in the position of asking that question i wouldn't ask for the right solution, i'd ask for ways that come to her mind how this problem could be solved, what pitfalls could arise in special cases. try to find out what she knows about programming, not what she knows about php. try to find out about intelligence, problem solving and creativity. altought experience matters a lot even when it comes to bang out code fast, it's not a constant.
the solutions i'd provide, the pros/cons and what it tells about me ...
built-in array_sum (very fast and definitley not buggy, but inflexible): i have a bit of experience with traditional php projects
for/loop constructs (good enough, reinventing the wheel. but can be used if there are different objects than numbers. pros: everybody will understand it): i can solve simple problems if there are no predefined copy&pasteable solutions
array_reduce (with an offering to implementat array_reduce, if the interviewer wants to see it): unusual for a php programmer, so it seems i have knowledge and experience outside of the php sandbox
an ArraySum-Object (with an ArraySum::add($value) method that keeps all values stored but caches the sum): i'm used to at least some of the oop-principles
function () { return 11; } (with the disclaimer that this is a joke solution, but valid): i have (albeit crude) programmer-specific humour - a sign i'm personally interested in programming outside of work ... some interviewers who are programmers (but not hackers) might interpret this as a willingness to use dirty hacks as placeholders (aehm) if time constraints are too tight
a recursive solution would be nice. i can probably solve a bit more complex, algorithily problems too and most likley know my way around simple trees and data structures
recursive divide and conquer: bonus! i know even more about algorithms.
try to get as much as possible out of this question (if time permits). in the end you'll know a little bit about programming capability and a lot about experience (altought not necessarily PHP specific).
i'd choose this question over letting the candidate write out quicksort - a very specific question about knowledge almost never needed in the web dev world - any time.
disclaimer
the question is useless when ...
the interviewer is not a programmer. forget it if a hr-guy is doing it
there's a very tight time constraint when interviewing. then the result is almost random anyway.
additionally, who are you looking for? if you need a cheap grunt coder, even a simple question like this should work. if you need quality and experience, don't waste too much time on it (but do it anyway).
No, it isn't too hard. If someone doesn't understand the concept of a loop or how to iterate through an array, they're not qualified as programmers. I'd also want them to know that there's a built-in function for that (array_sum()), or at least where to look for it.
You might want to take a look at The Five Essential Phone-Screening Questions, although you'll probably have to rework them a bit to suit your needs.
My own view is that there is a limit to the kind of toy questions you could ask for programming on a whiteboard. At best, these are simply toys that are often circulated on online forums and your candidates will memorize.
Most PHP developers created visible websites - you could see their work.
To me, a much better question would be to give him a complicated piece of your own production code and have him explain what it does or how it can be improved, etc. Most of the time will be spent doing maintenance anyway, better get an idea on his code reading skill, not just code writing.
Short Answer: No
Edit: Just to clarify I don't think this is a hard question at all. Regardless of the language. As others have posted, even if they can't get the syntax correct, the should at least be able to write it out in a reasonable pseudocode.
Long Answer:
I often ask interview questions I expect the candidate to miss. One could classify them as too (hard|vague|open-ended), but I am not really looking for an answer. I am looking to see the following:
Do they try to answer the question? Some people just give up immediately
How do they approach the problem? Even if they go down the wrong path are they generally making good assumptions and asking good questions?
How well do they maintain composure under stress? The question is designed to be hard, and therefore will be stressful. Do they panic, remain calm, withdraw, talk it out, etc...?
Are they able to find the solution if I give them hints and pointers? Or how well do they listen, and do they assimilate new information quickly?
Occasionally I am surprised with a candidate who is whip-smart, and just codes up a quick and elegant solution. Those are definite keepers. But I also find good candidates by people who miss the final solution, but are clearly thoughtful, logical, and given enough time would eventually solve the problem.
no, it isn't too hard, but it may cause people to panic if they do not exactly remember the syntax (though if you specifically ask for a php dev, then they should at least remember some syntax). Ask for pseudocode instead, if they still cannot do the question then there is a problem :)
If your applicant can't write a simple for loop and some addition on a whiteboard, you absolutely don't want them touching your code. Even as a front-end developer, they'll be using for loops all the time to output lists, table rows, image galleries and the like.
This is the type of basic thing you ask on the phone before bothering to bring a candidate in house.
There are a couple of standard things I ask every programmer about: Do a select on two tables to give a sum of a column in the second table, delete records from one table based on values in a second, difference between an object and a string as a method parameter, and a couple of html/css related questions.
Within 5 questions I can weed out 90% of the candidates before I even see them. The rest of it is going to boil down ideology.
My favorite would be:
while ($foo && $sum += array_shift($foo)) continue;
This question may be better improved by providing the documentation for the array() function, because if they don't know what it is, they could very easily look it up themselves in a job.
It's not too hard. If they cannot answer that question, they obviously cannot code their way out of a wet paper bag. I would definitely not hire such a person for any kind of development work.
Question is, how could you improve your recruiting process to avoid interviewing these candidates in the first place? Sounds to me like you're not screening your applicants enough before inviting them in for a chat.
If you can't write code to sum an array (in whatever language you prefer) I don't know what you can write. What on earth do you think someone could contribute to your project if they can't write code to do that question?
Actually, this questions seems kind of... easy.
I suppose writing it on a whiteboard makes it more difficult, though.
This question should be easy for people that have programming experience, but I'm guessing you may be getting a lot of designers that picked up PHP by copying/pasting code snippets in place.
Maybe you need to update your job listings to make them more programming centric and avoid web design terms.
No, it's not hard. What you've discovered is that there are a lot of "programmers" out there who can't program - they can memorize, they can copy and paste, but they don't actually understand what they are creating (in most cases they seem totally unaware of their lack of understanding).
This lack of understanding becomes painfully obvious when they are asked to write something simple from scratch - writing just the glue code, without all the complex stuff that they'd normally just grab as code snippets and then shift around until the compiler stops complaining.
In general you want to avoid these people like the plague, as they will consistently produce buggy code and will not understand why you or your customers think it doesn't work.
Jeff wrote about this a few years ago: Why Can't Programmers.. Program?
To be honest, I would like to think that if a person applies to a programming position, he or she will probably have the relevant skills on their resumes. Why not ask simple problem solving questions instead if the position doesn't require some sort special skills in the language in question? I was once asked how many pizza stores there are in my country. They were interested in checking how I approached the problem and weren't really interested in how awesome I might be in the relevant programming language. I think that was a good way to go about it. Am I awfully wrong in thinking that?
Edit: Or is it very common that people fake their resumes?
(I think the array_sum($array) method, as part of PHP, will do the job.)
The question really is trivial. Although there is enough space for error in a stressful situation but summing up an array should be easy enough for anyone with basic programming skills in any language.
It would take a dunce to muck up an interview with a question like this. The question is not too hard, it's actually very lenient.
It depends on what you're trying to ask. Are you screening their ability to recall syntax? Or are you looking for best-practice methods in dealing with array functions? If it's the first case, your question is fine.
On the other hand, if you're trying to see how well a person actually understands code, and knows implications based on how something is structured, the question is good, but instead of requiring them to write a line by line function, invite a discussion on how they would do it, and what would be some considerations with their answer. Why not do it via method B?
IME, asking for rote memory responses (syntax recall, port numbers, etc etc) tells you some aspects of an individuals ability, and sometimes need to be asked. But more important is digging into their problem solving abilities.
I don't see why anyone would have any problems with that. (Assuming that they are developers) And yes, programming at the whiteboard is unrealistic but that is a trivial question which any developer should be able to solve.
I had a deer-in-the-headlights moment wondering what the trick was!
Anyone applying for a programming job will know how to add integers together (one way or another, even if it's in a loop), so I'd skip it and find something more challenging....but not so confusing! :)
I've done interview recently for PHP position. I've been asked to write simple function on paper (of course not as simple as your example).
Anyway, when I've done that function (some 6 lines of Python code), interviewers where
pleased. They told me, that there are lot of ppl unable to write any code without IDE, and this small test serves to filter them out.
As for your example — it's just to simple. Especially if you accept array_sum() as an answer.
I wouldn't believe that there are such "programmers" out there, if you'd asked me a few years ago. But what has been seen cannot be unseen. I've witnessed firsthand people who make a living out of programming websites and know nothing about programming. They just copy and paste other people's code around, until they get it running. And you wouldn't possibly believe how their income level fares compared to their "skills" (yeah, income level does not directly relate to skills but it still freaks me out).
Yes, you are sane and those people do exist. And what you are doing is one of the useful filters for filtering "pragmatist script copy-pasters" (or others) from real coders. Of course, unless you want copy-pasters (they can accomplish some simple tasks! -or more complex ones but with unbelievable code-) in which case such an interview question is really hard for them.

What would be a good sample project to ask a prospective programmer to code during the hiring process?

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.

Categories