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.
Some other articles
J715 - Putting the Java Language Together The spirit of Java - delegating to classes This article Type checking, Java arrays and collections Good Programming practise - where to initialise variables Build on what you already have with OO R212 - Test::Unit Cucumber example - test::unit, scenario outlines, datafile driven test This article C239 - Putting it all together When do I use the this keyword in C++? Test driven development, and class design, from first principles (using C++) This article Reading files, and using factories to create vectors of objects from the data in C++ C++ - unknown array size, unknown object type. Help! Strings, Garbage Collection and Variable Scope in C++ Using C and C++ functions in the same program - how to do it Further C++ material - view new or old Make and makefiles - a commented example to help you learn Multiple Inheritance in C++ - a complete example Compile but do not run PHP - syntax check only Good Programming practise - where to initialise variables Code quality counts C++ - just beyond the basics. More you can do Build on what you already have with OO U196 - Testing and Development in Lua This article Y212 - Code testing, patterns, profiles and optimisation. Profiling your Python program Pytest - second example beyond hello world Pytest - starting example The principle of mocking - and the Python Mock package Unittest of a Flask application including forms Flask and unittest - hello web app test world Testing in Python 3 - unittest, doctest and __name__ == __main__ too. Combining tests into suites, and suites into bigger suites - Python and unittest Python base and inherited classes, test harness and unit testing - new examples This article Test Driven Development in Python - Customer Comes First Using Make for a distribution Testing your Python classes with the unittest package - how to Passing optional and named parameters to python methods A demonstration of how many Python facilities work together Pressing ^C in a Python program. Also Progress Bar. Defining a static method - Java, Python and Ruby Using Python with OpenOffice Advanced Python, Perl, PHP and Tcl training courses / classes Python decorators - wrapping a method call in extra code __new__ v __init__ - python constructor alternatives? Python GTK - Widget, Packing, Event and Feedback example Preparation for a day's work H115 - Designing PHP-Based Solutions: Best Practice Real life PHP application using our course training MVC example Using an MVC structure - even without a formal framework This article We not only teach PHP and Python - we teach good PHP and Python Practice! Even early on, separate out your program from your HTML! Filtering PHP form inputs - three ways, but which should you use? PHP sessions - a best practice teaching example Injection Attacks - PHP, SQL, HTML, Javascript - and how to neutralise them Separating program and artwork in PHP - easier maintainance, and better for the user How to build a test harness into your PHP Not just a PHP program - a good web application Adding a newsfeed for your users to a multipage PHP application Improving the structure of your early PHP programs Refactoring - a PHP demo becomes a production page Defensive coding techniques in PHP? PHP Techniques - a workshop Short and sweet and sticky - PHP form input Software to record day to day events and keep an action list Efficient PHP applications - framework and example A story about benchmarking PHP Ordnance Survey Grid Reference to Latitude / Longitude Converting from postal address to latitude / longitude Controlling and labelling Google maps via PHP Using a MySQL database to control mod_rewrite via PHP Easy handling of errors in PHP Resetting session based tests in PHP Drawing hands on a clock face - PHP Painting a masterpiece in PHP Good Programming practise - where to initialise variables Back button - ensuring order are not submitted twice (PHP) Learning to write secure, maintainable PHP Maintainable code - some positive advice Code quality counts Global, Superglobal, Session variables - scope and persistance in PHP PHP - good coding practise and sticky radio buttons Reporting on the 10 largest files or 10 top scores Giving the researcher power over database analysis Merging pictures using PHP and GD Robust checking of data entered by users A year on - should we offer certified PHP courses Code and code maintainance efficiency Putting a form online Crossfertilisation, PHP to Python Short underground journeys and a PHP book P711 - An Introduction to Standards in Perl This article Perl - making best use of the flexibility, but also using good coding standards A long day in Melksham ... Security considerations in programming - what do we teach? Designing your data structures for a robust Perl application About dieing and exiting in Perl Well structured coding in Perl A short Perl example Advanced Python, Perl, PHP and Tcl training courses / classes Dont just convert to Perl - re-engineer! Perl and Shell coding standards / costs of an IT project Bathtubs and pecking birds Maintainable code - some positive advice KISS - one action per statement please - Perl Code quality counts How to debug a Perl program Python - block insets help with documentation Satisfaction of training Q456 - Test Driven Development and Behaviour Driven Development Testing new algorithms in PHP Regression testing - via a very short C testing framework The principle of mocking - and the Python Mock package Test framework for TCL - Tcltest - some examples Regression Testing my website - Cucumber and Watir Behaviour Driven Development / Ruby and Cucumber Test driven development, and class design, from first principles (using C++) A behaviour driven example of writing a Java program Test Driven Development - a first example of principle in C This article Q100 - Learning to Progam Learning not just what a program does, but how to design it in the first place. Learning to program sample program - past its prime, but still useful This article Learning to program - what are algorithms and design patterns? Learning to program - variables and constants Learning to program - Loop statements such as while Learning to Program - the conditional statement (if) Learning to Program - how we start to teach you at Well House Consultants Reading and checking user inputs - first lessons - Ruby Flowchart to program - learning to program with Well House Some terms used in programming (Biased towards Python) Learning to write good programs in C and C++ - separating out repeated code Learning to program - where to start if you have never programmed before Programming Standards from the start! I almost put the bins out this morning Learning to program in ... Learn a new programming language this summer. Can you learn to program in 4 days? New to programming? It is natural (but needless) for you to be nervous Tracking difficult bugs, the programmer / customer relationship Learning to program in PHP, Python, Java or Lua ... I have not programmed before, and need to learn Learning to program as a part of your job Best source to learn Java (or Perl or PHP or Python) Learning and understanding scripting programming techniques The next generation of programmer