Friday, April 20, 2012

Python coding conventions

It is often a confusion in my team regarding what practice to follow while coding in python.
I have research it (mainly from PEP-08) and am sharing my findings.
Code Style
==========
Idioms
::::::
Zen of Python (PEP-20)
----------------------
Type import this on python shell to see the zen of python.

The Zen of Python, by Tim Peters
Beautiful is better than ugly.
Explicit is better than implicit.
Simple is better than complex.
Complex is better than complicated.
Flat is better than nested.
Sparse is better than dense.
Readability counts.
Special cases aren't special enough to break the rules.
Although practicality beats purity.
Errors should never pass silently.
Unless explicitly silenced.
In the face of ambiguity, refuse the temptation to guess.
There should be one-- and preferably only one --obvious way to do it.
Although that way may not be obvious at first unless you're Dutch.
Now is better than never.
Although never is often better than *right* now.
If the implementation is hard to explain, it's a bad idea.
If the implementation is easy to explain, it may be a good idea.
Namespaces are one honking great idea -- let's do more of those!


PEP-8

=====
Naming Conventions
------------------
As the naming conventions of python are otherwise loosely defined, some rules were created to be followed by all standardized modules.
In this, the python community is undecided. Generally, the java convention is followed, but with an underscore instead of capital letter between letters in a word, but capital case as in C# is also observed.

Underscore usage:
-----------------
This is not a syntactical requirement, but a convention.
 _single_leading_underscore
 weak "internal use" indicator. Eg; from M import * does not import objects in M which start with an _
 single_trailing_underscore_
 used by convention to avoid conflicts with Python keyword. Eg; class_ m


Abbreviations should be capitalized like URLBroadcastListener



Code lay-out
------------
Use of 4 spaces per indentation level, avoid tabs and do not mix tabs with spaces.
Do not exceed 80 character lines.
Avoid compound statements (single line having more than one line of code separated by a semicolon ; )
Blank lines can be used to perform the following:
To separate logical spaces(only if necessary) within the methods.
To separate different methods within a class.
Class definitions and functions may have 2 blank lines in between.

Imports
-------
Each should be on separate lines, but could be supplied on the same line if presnet in same namespace.
Order of imports:
----------------
  Standard imports
  Related third party imports
  Local application/library imports
Use absolute imports from within the namespace instead of relative values.
Specify clearly, if using a module containing a class as: from namespace.classname import classname to reduce ambiguity

WhiteSpaces
-----------
Whitespace formatting is best left to our own descretion, and should make the code readable.
Reiterating this often forgotten best practice- Never mix tabs with spaces.
Avoid WhiteSpaces at:
Just after start of parenthesis or a method call. eg: def meth ( arg): #Both the spaces around (
Just before a comma, semicolon or a colon. eg: def meth(arg , arg2) :
Just before indexes. eg: collect ['paper']
More than a single whitespace around operators. eg: pi  =  3.14159
No whitespaces should be used around keyword arguments or in assigning default parameter values
Compound statements on the same line (separated with a ; or : ) are discouraged as they affect readability.


Comments & Documentation strings
--------------------------------
Here too, common programming rules apply: Comments should only be used if code is not easily decipherable; and should be updated with code changes.
Comments should be complete line in itself with longer ones finishing with a period (.)
Block comments start before any block of code with a single # and a space.
Inline comments should be rarely used, if that particular line performs something critical for the developer's attention.
Documentation strings (aka documentation comments in some languages) should be written for all public classes, methods, functions and modules.
These should preferably be in multiple line.

PEP-257
=======
Docstring Conventions
---------------------
These conventions are optional, as they pertain to the documentation portion of python. Still, these can be quite handy if you would be releasing the api documentation of your application later as api generators like Docutils require that you conform to a specified convention.
Docstring is a string literal occuring at the first statement of a method or class.
It is created using three " literals and can be single or multi line.

It is worth noting that the zen of python must take precedence over yours or mine preferences. This is necessary to allow programmers from diverse backgrounds to communicate effectively in code (ours was a mix of java, C# and visual basic programmers and we were using a wrapper of a C++ library, leading to major headaches and refactoring towards code maintenance).

Monday, April 2, 2012

"Programming Entity Framework DbContext" by Julia Lerman & Rowan Miller; O'Reilly Media

This is my review of the book, programming entity framework DbContext by Julia Lerman & Rowan Miller, done under the Oreilly Blogger Review Program.

Targeted at developers familiar with, and using entity framework in their applications, especially at places where object context interacts with the core of the framework, this book offers developers all about DbContext API, with the how-tos for dealing with creating customized queries to the database when the built-in mechanism of the framework does not suffice. Julia Lerman is the leading authority on learning Entity Framwork and Rown Miller is the project manager in Microsoft's team of ADO.NET Entity Framework.



The point of having this book is simple, after all that ease of creation of database entity models (and their corresponding configuration files) , one needs to interact them with application code where middle tier code performs interactions with the entities.

The book jumps into the differences between DbContext and ObjectContext at the start and explains the download instructions as well as code examples explaining integration with outside code as well as edmx model designer. It then explains the query part  and demonstrates LINQ queries to interact with the entities using DbSet in an eloquent manner while explaining entitiy retrival in detail (something that is rare to find by in a .NET text). I felt at ease with the details and quality of the coverage of the DbContext API and it almost felt like an in depth coverage into an established ORM tool like Hibernate or JPA while dealing with entities and relationship sets.It then proceeds to explain problems and solutions regarding tracking change of entities without the availability of a database, as the disconnected context state management is a feature which is hard to figure by itself in n-tiered applications.

The second half of the book deals with the newly released contents in the entity framework. It covers change tracker in detail and provides ample code along with the details of the new api. The validation api is also new in the framework and is introduced comprehensively, and some of the examples that I attempted worked correctly. The customization of validations is also covered in detail which is very handy to use in practical applications. The chapter on advanced features is mostly about unit testing with dbcontext, and should be named so instead of its generic name.
The book finishes off with the insight about the upcoming entity framework 5, but lacks any code example as the beta for the same is not out.

Overall, the book follows a style quite similar to a cookbook, but packs in with some well guided theory as well. The lack of appendix is missing, which could be there instead of the last chapter but the rest of the book follows the contents around the topic and is indeed a pleasurable learning experience. For developers looking forward to another .NET book with extensive visuals and wizards, this would come as a disappointment but for those looking to solve their middle tier infrastructure plumbing with proper code, this is the solid reference to  be kept near while developing.
You can purchase this book from here.