Main Content

Learning to program - comments, documentation and test code

Archive - Originally posted on "The Horse's Mouth" - 2014-11-22 15:32:53 - Graham Ellis

Updates material from our courses for newcomers to programming ... we're very happy to help newcomers learn about the basic principles of programming, running an extra day for a very small group on the front of our regular courses for delegates who have programmed before, but in different languages.




In this final session of "learning to program in xxx", I'm going to stress the importance of some of the more mundane elements, but practical requirements of programming.

1. You should comment your code so that the PROGRAMMER who follows behind you (or yourself in a year or two) can understand what has been done, and pick it up, fix issues, and update it. You should also include things like a version number so that you're not left puzzling which version is which, nor fixing an old version

2. You should document your code so that the USER who makes use of it knows how to do so. That user could be someone visiting your web page, running your application, or another programmer calling in elements of your code as part of his program; we've seen the use of library routines during the day so far ... and YOU may be providing such library routines.

3. You should provide SAMPLE / TEST code so that you can test the continued operatation of the application / routines in the future, and ensure that they're still running right when you transfer a copy to a computer running a different operating system.

Comments and documentation are not, entirely, extras that you have to provide in addition to the running code. By a good choice of variable names, and by insetting the code sensibly and spacing it out, you're doing much of than work within the code. And your test code not only helps you get the code right in the first place, but also provides examples of how it should be used for others who'll be making use of your code.