Home Accessibility Courses Twitter The Mouth Facebook Resources Site Map About Us Contact
 
For 2023 (and 2024 ...) - we are now fully retired from IT training.
We have made many, many friends over 25 years of teaching about Python, Tcl, Perl, PHP, Lua, Java, C and C++ - and MySQL, Linux and Solaris/SunOS too. Our training notes are now very much out of date, but due to upward compatability most of our examples remain operational and even relevant ad you are welcome to make us if them "as seen" and at your own risk.

Lisa and I (Graham) now live in what was our training centre in Melksham - happy to meet with former delegates here - but do check ahead before coming round. We are far from inactive - rather, enjoying the times that we are retired but still healthy enough in mind and body to be active!

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

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

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

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

P306 - Perl - Plain Old Documentation
  [760] Self help in Perl - (2006-06-14)


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., 2024: 48 Spa Road • Melksham, Wiltshire • United Kingdom • SN12 7NY
PH: 01144 1225 708225 • EMAIL: info@wellho.net • WEB: http://www.wellho.net • SKYPE: wellho

PAGE: http://www.wellho.info/mouth/668_Pyth ... ation.html • PAGE BUILT: Sun Oct 11 16:07:41 2020 • BUILD SYSTEM: JelliaJamb