I am often asked to look at other people’s programming projects these days. I really enjoy this most of the time. Sometimes this is part of evaluating an entry into a programming or software development contest. Sometimes it is to give feedback or debugging help on student or sample teacher produced code. Either way I have learned a few things about problems with sending code and would like to share some of what I have learned. So a few guidelines.
Send enough of the project – What is enough? That depends on a lot of things. But if you want someone to actually compile and run your project you probably need at least the whole project folder. My advice is to package things up and test them before you send it. Take the package to a clean system – one that you haven’t been working on this project and unpack your package. Does what you moved compile and run there? If not, what is needed to make it run? Is it just standard libraries or a special SDK or some specific set up – SQL server perhaps? If the person you are sending things to can not be expected to have to easily get (with your warning and instruction) something for their system you need to send it. This all brings us to the next guideline.
Send directions – What sort of directions? Well for starters how to unpack and or install what you are sending. Also any prerequisite software. What version of relevant software (compiler, IDE, OS, SDK, etc) you using for example. This will help determine if an older or newer versions fix or cause things to work or not work. Chances are that people will not spend a lot of time trying to make things work without instructions. If you are entering a contest a judge is very likely to decide the code just does not work and allocate no points at all. Trust me on this – I speak as a judge. In fact if you are submitting something for judging you may want to ask a friend to do a dry run with your package and instructions. You really want to make things simple for the judges.
Make sure the tester/evaluator/debugger/advisor has enough information to run the program. If you have a login screen make sure you tell them what information will get them in. You don’t want them to have to read the code or worse still hack the code to run your software. Provide sample data for them to use. Sure they will try to come up with some data that may break things but you want to make sure they have data that shows off the best of your code.
Use good coding practices – No matter if your code is being judged/graded or debugged it is helpful if names make sense, comments are provided and and other standard practices are maintained. Actually those things help avoid needing help debugging in the first place. A word to the wise about code that is being graded – if you have five forms named Form1, Form2, Form3, Form4 and Form5 it will reflect poorly on you and your project. Sure you may know which one is the login form, the report form, the help form, the data input form and the really impressive super duper sure to impress form but no one else does. You can make life a lot easier for someone debugging the code to start with good form names. Variable, object, method and property names are just as important. Don’t make people work if you want something good in return for their time.
For debugging help clearly explain the problem - “This code doesn’t work” is not a helpful statement. Why? Because in all likelihood the person you are sending it to has no idea what “working” looks like! Explain what is happening, what should be happening and what assumptions you are making in the process. Outline the steps that can be taken to reproduce the problem – in detail! You should also explain some of the things you have already done to try and track down the problem. But at a minimum don’t make the person guess as to what the problem is.
Now you may think the problem is obvious but if there is the slightest thing different on the other person’s set up (see earlier guidelines) that may mask your problem. You want someone to look at the right problem and not one you have already solved.
Bringing in a second set of eyes to look at a programming problem or review it for improvement is often a great idea. But you want to make sure you maximize the value of the process by minimizing the work the other person has to do. Take your time, think about what you are doing and test before you send and everyone will be happier in the long run.
Very good advice. Two of your points on debugging are important from a teaching standpoint -->
(1) Make the student describe what the program _should_ do -- quite often just articulating the specs will make a problem self-apparent and my help won't even be needed.
(2) Also, with students I encourage them to tell me what they've already tried. After all, many students will get 50% of the way there, and just need a hint to get "over the hump." By describing what they've done, they realize that I'm not giving them the whole answer, just helping with one step -- and this gives them confidence so the next time they'll be motivated to get 90% or even 100% of the way on their own -- and they'll become more aware of the progress that they're making! On the flip side, some students give up too soon, and by making them describe what they've already done, it forces them to give an honest effort before "throwing up their hands."