Home Accessibility Courses Twitter The Mouth Facebook Resources Site Map About Us Contact
 
Python and Tcl - public course schedule [here]
Private courses on your site - see [here]
Please ask about maintenance training for Perl, PHP, Lua, etc
 
Python - block insets help with documentation

For many programmers, documenting their code is a chore, yet every piece of code that's going to be (re)used needs both instructions for the user, and adequate explanation of techniques for the code maintainer. The need for BOTH of these forms of support documentation is often overlooked by the newcomer, but that's really a subject for another day ...

In some languages such as Perl, you can write code that's crystal clear, easy to follow, and has the artistic beauty of a Rembrandt. And you can also write code that makes a dog's dinner look pretty. It's up to the development team and their managers to set coding styles and standards - see our sample standards document for an example of what's good and bad practise. Then in Perl you can use POD (Plain Old Documentation) to provide your user docs.

Python is particularly clever in that it forces certain good practise on the programmer, yet without imposing the need for extra levels of declaration. And it does this by using simple techniques such as the indented block structure. example.

When I first came to Python (I admit it), I swore and cursed at the need to inset blocks! But I've learn just how clever that structure really is. You loose a rats nest of { and } characters (and there's no "done", "endif" or "fi" either) and you gain a layout where you can very clearly see which code goes with which conditional statement. Try it once, and you'll hate it. Try it three times, and you'll love it and never want to go back to the bad old ways. And it helps make you code self documenting with that documentation remaining up to date with code changes.

On the user documentation side too, Python has some great tools. Documentation strings allow you to provide structured documentation with each module and each defined function or method, and that documentation can be explored with automated tools such as pydoc. Whether you're writing classes to be called by other programmers, or top level applications, you'll be thanked a thousand times over by your users even if they don't actually email you to say it. Oh - and with documentation strings, the instructions remain in the same file as the source so that they won't get lost at the point of distribution!
(written 2006-04-04, updated 2006-06-05)

 
Associated topics are indexed as below, or enter http://melksh.am/nnnn for individual articles
P306 - Perl - Plain Old Documentation
  [760] Self help in Perl - (2006-06-14)
  [242] Satisfaction of training - (2005-03-11)

P711 - An Introduction to Standards in Perl
  [4326] Learning to program - comments, documentation and test code - (2014-11-22)
  [3398] Perl - making best use of the flexibility, but also using good coding standards - (2011-08-19)
  [2875] A long day in Melksham ... - (2010-07-17)
  [2688] Security considerations in programming - what do we teach? - (2010-03-22)
  [2375] Designing your data structures for a robust Perl application - (2009-08-25)
  [1863] About dieing and exiting in Perl - (2008-11-01)
  [1853] Well structured coding in Perl - (2008-10-24)
  [1728] A short Perl example - (2008-07-30)
  [1555] Advanced Python, Perl, PHP and Tcl training courses / classes - (2008-02-25)
  [1395] Dont just convert to Perl - re-engineer! - (2007-10-18)
  [1345] Perl and Shell coding standards / costs of an IT project - (2007-09-11)
  [1221] Bathtubs and pecking birds - (2007-06-07)
  [1047] Maintainable code - some positive advice - (2007-01-21)
  [965] KISS - one action per statement please - Perl - (2006-12-05)
  [945] Code quality counts - (2006-11-26)
  [743] How to debug a Perl program - (2006-06-04)

Y103 - Python - Conditionals and Loops
  [4723] Conditional operators in Python - (2016-11-05)
  [4713] Equality (in Python) - (2016-10-30)
  [4545] Method, Class, Module, Package - how to they relate in Python? - (2015-10-17)
  [4541] Setting up and tearing down with the Python with keyword - (2015-10-16)
  [4402] Finding sum, minimum, maximum and average in Python (and Ruby) - (2015-01-19)
  [4323] Learning to program - Loop statements such as while - (2014-11-22)
  [4322] Learning to Program - the conditional statement (if) - (2014-11-21)
  [4210] If elif elif elif - multiway selection in Python - (2013-11-16)
  [4092] Identity in Python - (2013-05-17)
  [3895] Flowchart to program - learning to program with Well House - (2012-10-14)
  [3762] Learning to program - the if statement. Python. - (2012-06-12)
  [3620] Finding the total, average, minimum and maximum in a program - (2012-02-22)
  [3558] Python or Lua - which should I use / learn? - (2011-12-21)
  [3439] Python for loops - applying a temporary second name to the same object - (2011-09-14)
  [3397] Does a for loop evaluate its end condition once, or on every iteration? - (2011-08-18)
  [3200] How a for loop works Java, Perl and other languages - (2011-03-12)
  [3083] Python - fresh examples from recent courses - (2010-12-11)
  [2899] Groupsave tickets - 3 or 4 train tickets for the price of 2 - (2010-08-02)
  [2778] Learning to program in Python 2 ... and / or in Python 3 - (2010-05-24)
  [1696] Saying NOT in Perl, PHP, Python, Lua ... - (2008-07-04)
  [1661] Equality, sameness and identity - Python - (2008-05-31)
  [1477] Decisions - small ones, or big ones? - (2007-12-18)
  [1201] No switch in Python - (2007-05-23)
  [909] Python is like a narrowboat - (2006-10-30)
  [835] Python - when to use the in operator - (2006-08-16)
  [788] New - Conditional expressions in Python 2.5 - (2006-07-01)
  [657] The ternary operator in Python - (2006-03-25)
  [353] Wimbledon Neck - (2005-06-20)
  [299] What - no switch or case statement? - (2005-05-03)

Y105 - Python - Functions, Modules and Packages
  [4724] From and Import in Python - where is the module loaded from? - (2016-11-06)
  [4722] Embedding more complex code into a named block - (2016-11-04)
  [4719] Nesting decorators - (2016-11-02)
  [4662] Recursion in Python - the classic example - (2016-03-07)
  [4645] What are callbacks? Why use them? An example in Python - (2016-02-11)
  [4448] What is the difference between a function and a method? - (2015-03-04)
  [4441] Reading command line parameters in Python - (2015-02-23)
  [4410] A good example of recursion - a real use in Python - (2015-02-01)
  [4407] Python - even named code blocks are objects - (2015-01-28)
  [4361] Multiple yields and no loops in a Python generator? - (2014-12-22)
  [4212] Python functions - an introduction to how they work - (2013-11-16)
  [4161] Python varables - checking existance, and call by name or by value? - (2013-08-27)
  [4029] Exception, Lambda, Generator, Slice, Dict - examples in one Python program - (2013-03-04)
  [3945] vargs in Python - how to call a method with unknown number of parameters - (2012-12-06)
  [3931] Optional positional and named parameters in Python - (2012-11-23)
  [3885] Default local - a good choice by the author of Python - (2012-10-08)
  [3852] Static variables in Python? - (2012-08-29)
  [3766] Python timing - when to use a list, and when to use a generator - (2012-06-16)
  [3695] Functions are first class variables in Lua and Python - (2012-04-13)
  [3662] Finding all the unique lines in a file, using Python or Perl - (2012-03-20)
  [3474] Python Packages - groupings of modules. An introduction - (2011-10-11)
  [3472] Static variables in functions - and better ways using objects - (2011-10-10)
  [3464] Passing optional and named parameters to python methods - (2011-10-04)
  [3459] Catching the fishes first? - (2011-09-27)
  [3280] Passing parameters to Python functions - the options you have - (2011-05-07)
  [3159] Returning multiple values from a function call in various languages - a comparison - (2011-02-06)
  [2998] Using an exception to initialise a static variable in a Python function / method - (2010-10-13)
  [2994] Python - some common questions answered in code examples - (2010-10-10)
  [2929] Passing a variable number of parameters in to a function / method - (2010-08-20)
  [2878] Program for reliability and efficiency - do not duplicate, but rather share and re-use - (2010-07-19)
  [2766] Optional and named parameters to Python functions/methods - (2010-05-15)
  [2718] Python - access to variables in the outer scope - (2010-04-12)
  [2520] Global and Enable - two misused words! - (2009-11-30)
  [2506] Good example of recursion in Python - analyse an RSS feed - (2009-11-18)
  [2481] Sample code with errors in it on our web site - (2009-10-29)
  [2440] Optional parameters to Python functions - (2009-10-07)
  [2439] Multiple returns from a function in Python - (2009-10-06)
  [2011] Conversion of OSI grid references to Eastings and Northings - (2009-01-28)
  [1879] Dynamic code - Python - (2008-11-11)
  [1871] Optional and named parameters in Python - (2008-11-05)
  [1870] What to do with a huge crop of apples - (2008-11-04)
  [1869] Anonymous functions (lambdas) and map in Python - (2008-11-04)
  [1790] Sharing variables with functions, but keeping them local too - Python - (2008-09-09)
  [1784] Global - Tcl, PHP, Python - (2008-09-03)
  [1464] Python Script - easy examples of lots of basics - (2007-12-08)
  [1202] Returning multiple values from a function (Perl, PHP, Python) - (2007-05-24)
  [1163] A better alternative to cutting and pasting code - (2007-04-26)
  [1134] Function / method parameters with * and ** in Python - (2007-04-04)
  [959] It's the 1st, not the 1nd 1rd or 1th. - (2006-12-01)
  [949] Sludge off the mountain, and Python and PHP - (2006-11-27)
  [913] Python - A list of methods - (2006-11-03)
  [912] Recursion in Python - (2006-11-02)
  [900] Python - function v method - (2006-10-20)
  [821] Dynamic functions and names - Python - (2006-08-03)
  [775] Do not duplicate your code - (2006-06-23)
  [749] Cottage industry or production line data handling methods - (2006-06-07)
  [745] Python modules. The distribution, The Cheese Shop and the Vaults of Parnassus. - (2006-06-05)
  [561] Python's Generator functions - (2006-01-11)
  [418] Difference between import and from in Python - (2005-08-18)
  [386] What is a callback? - (2005-07-22)
  [340] Code and code maintainance efficiency - (2005-06-08)
  [308] Call by name v call by value - (2005-05-11)
  [303] Lambdas in Python - (2005-05-06)
  [294] Python generator functions, lambdas, and iterators - (2005-04-28)
  [105] Distance Learning - (2004-10-31)
  [96] Variable Scope - (2004-10-22)

Y116 - Python - Applying OO design techniques and best practise
  [4718] Defining an object that is a modified standard type in Python - (2016-11-02)
  [4359] How to avoid too many recalculations within an object - (2014-12-21)
  [4118] We not only teach PHP and Python - we teach good PHP and Python Practice! - (2013-06-18)
  [4028] Really Simple Class and Inheritance example in Python - (2013-03-04)
  [3887] Inheritance, Composition and Associated objects - when to use which - Python example - (2012-10-10)
  [2604] Tips for writing a test program (Ruby / Python / Java) - (2010-01-29)
  [2523] Plan your application before you start - (2009-12-02)
  [2485] How do I set up a constant in Python? - (2009-10-31)
  [2407] Testing code in Python - doctest, unittest and others - (2009-09-16)
  [2363] Alpaca Case or Camel Case - (2009-08-16)
  [1181] Good Programming practise - where to initialise variables - (2007-05-09)
  [836] Build on what you already have with OO - (2006-08-17)
  [656] Think about your design even if you don't use full UML - (2006-03-24)


Back to
Well House Manor goes ahead
Previous and next
or
Horse's mouth home
Forward to
The best Open Source library in town
Some other Articles
Keeping your regular expressions simple
Both ends of the animal
Architectural Heritage - Devizes
The best Open Source library in town
Python - block insets help with documentation
Well House Manor goes ahead
Database design - get it right from first principles
PHP Image viewing application
Ruby course - oops - it's not happening
Python to MySQL
4759 posts, page by page
Link to page ... 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32, 33, 34, 35, 36, 37, 38, 39, 40, 41, 42, 43, 44, 45, 46, 47, 48, 49, 50, 51, 52, 53, 54, 55, 56, 57, 58, 59, 60, 61, 62, 63, 64, 65, 66, 67, 68, 69, 70, 71, 72, 73, 74, 75, 76, 77, 78, 79, 80, 81, 82, 83, 84, 85, 86, 87, 88, 89, 90, 91, 92, 93, 94, 95, 96 at 50 posts per page


This is a page archived from The Horse's Mouth at http://www.wellho.net/horse/ - the diary and writings of Graham Ellis. Every attempt was made to provide current information at the time the page was written, but things do move forward in our business - new software releases, price changes, new techniques. Please check back via our main site for current courses, prices, versions, etc - any mention of a price in "The Horse's Mouth" cannot be taken as an offer to supply at that price.

Link to Ezine home page (for reading).
Link to Blogging home page (to add comments).

You can Add a comment or ranking to this page

© WELL HOUSE CONSULTANTS LTD., 2019: 404 The Spa • Melksham, Wiltshire • United Kingdom • SN12 6QL
PH: 01225 708225 • EMAIL: info@wellho.net • WEB: http://www.wellho.net • SKYPE: wellho

PAGE: http://www.wellho.net/mouth/668_Pyth ... ation.html • PAGE BUILT: Sat May 27 16:49:10 2017 • BUILD SYSTEM: WomanWithCat