Difference between revisions of "My Python Coding Conventions"

From OpenCircuits
Jump to navigation Jump to search
Line 1: Line 1:
 
= Coding Conventions Etc. =
 
= Coding Conventions Etc. =
  
In reading the code it may be of some use to know what conventions I have ( tried ) to follow.  The code has been developed over quite a period of time so the standards are not uniform.  What I write here are the standards that are in quite a bit of the code and the directions that I am trying to move.  In all of the coding consistency is an important standard, I have a ways to go. Here are some types of conventions.
+
In reading my code it may be of some use to know what conventions I have ( tried ) to follow.  The code has been developed over quite a period of time so the standards are not uniform.  What I write here are the standards that are in quite a bit of the code and the directions that I am trying to move.  In all of the coding consistency is an important standard, I have a ways to go. I am now only coding in Python 3.6 or up. Here are some types of conventions.
  
 
== Names ==
 
== Names ==
Be consistent: this is good but have not been very successful in standards: I keep changing my mind. Names across classes are pretty consistent.  I am avoiding short names and try to make them descriptive enough that they are somewhat self documenting.  References are often copied across objects for easy access ( lots of parameters for example ); when this happens the name of the object is generally ( should be always ) the same in both objects.
+
I try to be consistent: this is good but have not been very successful in standards: I keep changing my mind.   I am avoiding short names and try to make names descriptive enough that they are somewhat self documenting.  References are often copied across objects for easy access ( lots of parameters for example ); when this happens the name of the object is generally ( should be always ) the same in both objects.
  
 
== Formatting ==
 
== Formatting ==
Line 11: Line 11:
  
 
== Docstrings ==
 
== Docstrings ==
Work towards using them.  Not good as of 2017 Jan
+
I am working towards using them but have not arrived at a format that I both like to read and which is quick enough to write.  Not good as of 2017 Jan
  
 
== Imports ==
 
== Imports ==
 
*In most cases use the format "import xyz" so the name space is not polluted and so it is easy to identify just what an imported class is.
 
*In most cases use the format "import xyz" so the name space is not polluted and so it is easy to identify just what an imported class is.
 
*In in objects that are almost all GUI then using "from Tkinter import *"  is ok but better is: "import Tkinter as Tk"
 
*In in objects that are almost all GUI then using "from Tkinter import *"  is ok but better is: "import Tkinter as Tk"
*I normally have only one or a few classes in a file so there is a lot of what I call "local imports".   
+
*I normally have only one or a few classes in a file so there are a lot of files and a lot of what I call "local imports".   
 
*Almost all imports are at the top of a file, std library imports first then "local imports".
 
*Almost all imports are at the top of a file, std library imports first then "local imports".
  
 
== Object Orientation ==
 
== Object Orientation ==
  
Almost everything is a class.  Not much in the way of module functions, not many classes in a module.  I am trying to have all my classes descend from something be it only Object. And now that I am in Python 3.6 this is how it always works.
+
Almost everything is a class.  Not much in the way of module functions, not many classes in a module.  I think my Java experience has led me to overuse classes and under use functions.... at the module level.
  
 
== Documentation for Class Instance Methods ==
 
== Documentation for Class Instance Methods ==

Revision as of 08:46, 11 September 2019

Coding Conventions Etc.

In reading my code it may be of some use to know what conventions I have ( tried ) to follow. The code has been developed over quite a period of time so the standards are not uniform. What I write here are the standards that are in quite a bit of the code and the directions that I am trying to move. In all of the coding consistency is an important standard, I have a ways to go. I am now only coding in Python 3.6 or up. Here are some types of conventions.

Names

I try to be consistent: this is good but have not been very successful in standards: I keep changing my mind. I am avoiding short names and try to make names descriptive enough that they are somewhat self documenting. References are often copied across objects for easy access ( lots of parameters for example ); when this happens the name of the object is generally ( should be always ) the same in both objects.

Formatting

Nothing special here but I like white space and use a lot. This is not standard Python. But this is what I like.

Docstrings

I am working towards using them but have not arrived at a format that I both like to read and which is quick enough to write. Not good as of 2017 Jan

Imports

  • In most cases use the format "import xyz" so the name space is not polluted and so it is easy to identify just what an imported class is.
  • In in objects that are almost all GUI then using "from Tkinter import *" is ok but better is: "import Tkinter as Tk"
  • I normally have only one or a few classes in a file so there are a lot of files and a lot of what I call "local imports".
  • Almost all imports are at the top of a file, std library imports first then "local imports".

Object Orientation

Almost everything is a class. Not much in the way of module functions, not many classes in a module. I think my Java experience has led me to overuse classes and under use functions.... at the module level.

Documentation for Class Instance Methods

Look something like this:

   def create_class_from_strings( self, module_name, class_name):
       """
       This will load a class from string names
       It makes it easier to specify classes in the parameter file.
       I believe it is used for both the comm drive and the "processor"
       args:  strings
       ret:   instance of the class
       Side effects Class created 
       """

The comment should give the intent of the method, some hint as to the args ( which hopefully have good names ), and some info. on the return value. zip means nothing, void....

I am moving toward using __ and _ as prefixes for more private methods, but have not gone too far in this direction.


Links

Configuration Files For Python [Category:Python]]