|
Training, Open Source Computer Languages |
| Home | Accessibility | Courses | Diary | The Mouth | Forum | Resources | Site Map | About Us | Contact |
|
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) 4061 Associated topics are indexed under 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 [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 [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 [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 [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) 5764
Some other Articles
Keeping your regular expressions simpleBoth 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 |
4081 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 at 50 posts per pageThis 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).
PH: 01144 1225 708225 • FAX: 01144 1225 899360 • EMAIL: info@wellho.net • WEB: http://www.wellho.net • SKYPE: wellho
PAGE: http://www.wellho.net/mouth/668_Pyth ... ation.html • PAGE BUILT: Sat Feb 23 12:39:13 2013 • BUILD SYSTEM: wizard