Editing My Python Coding Conventions

Jump to navigation Jump to search

Warning: You are not logged in. Your IP address will be publicly visible if you make any edits. If you log in or create an account, your edits will be attributed to your username, along with other benefits.

The edit can be undone. Please check the comparison below to verify that this is what you want to do, and then save the changes below to finish undoing the edit.

Latest revision Your text
Line 1: Line 1:
 
= Coding Conventions Etc. =
 
= 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.  Ultimately if you want to understand the code, read it.  I work hard to make it readable, so please try, you can let me know of shortcoming, but note that I am aware of the fact that it still need improvement.  You also might be interested in [[Russ Python Tips and Techniques]].
+
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.  Ultimately if you want to understand the code, read it.  I work hard to make it readable, so please try, you can let me know of shortcoming, but note that I am aware of the fact that it still need improvement.
  
 
== Names ==
 
== 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.  I am beginning to use leading underscores for private methods but just beginning this.  So far not doing the same for variables.
+
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 ==
  
 
Nothing special here but I like white space and use a lot.  This is not standard Python.  But this is what I like.
 
Nothing special here but I like white space and use a lot.  This is not standard Python.  But this is what I like.
 
== Comments ==
 
 
Comments are used for:
 
* Documentation
 
* Notes about subtleties in the code or other possible non obvious behavior.
 
* Ideas about code modifications for speed, enhancement .... !! marks an idea with high commitment ?? for one that is just an idea.
 
* Dead code that I want for reference for at least a while.
 
* Commented out code that might be useful for debugging: # will appear in column 1.  Not maintained so may or may not work.
 
* As usual always be skeptical about comment content.
 
 
Comment in column 1 is often for debugging while other comments, indented, end of line, or triple quotes are more often documentation.
 
  
 
== Docstrings ==
 
== 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 2019 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
* Function docstrings may say '''what it says''' if I think the function name is pretty much and explanation.  Especially if the function is short.
 
  
 
== Imports ==
 
== Imports ==
Line 54: Line 41:
 
I am moving toward using __ and _ as prefixes for more private methods, but have not gone too far in this direction.
 
I am moving toward using __ and _ as prefixes for more private methods, but have not gone too far in this direction.
  
= Application Structure =
+
== Application Structure ==
 +
coming...
 +
 
  
 
=== MVC Structure ===
 
=== MVC Structure ===
I try to separate the Model, View, and Controller into separate modules and classes.  The View is the class GUI.  The controller is normally the main routine where the app is started.
+
I try to separate the Model, View, and Controller into separate modules and classes.  The View is the class GUI.
  
 
=== GUI Structure ===
 
=== GUI Structure ===
 
+
coming...
*Construct frame by frame in a subroutine for each frame returning the frame reference, the caller then places the frame.  Typically constructed and placed from top to bottom from left to right.
+
*Construct frame by frame in a subroutine returning the frame reference, the caller then places the frame.  Typically constructed and placed from top to bottom from left to right.
*Elements Typically Included:
+
*Elements:
 
** Buttons for application management: restart the app, edit the parameters, edit the log, help.
 
** Buttons for application management: restart the app, edit the parameters, edit the log, help.
** Buttons.... for the application, depending on the application.
+
** Buttons.... for the application.
** Data Entry and Display widgets as required.
+
** A text control for application messages, sort of a mini console for the application.
** A scrolling text panel control for application messages, sort of a mini console for the application.
 
  
 
=== Application Parameters ===
 
=== Application Parameters ===
Line 73: Line 61:
  
 
=== Typical Application Functionality ===
 
=== Typical Application Functionality ===
Some functions seem helpful in most applications:
+
coming...
*Application Title: Program Name, Version, and Mode.
 
*GUI color: often set in parameters.py so multiple instances are distinguished at a glance.
 
*Help
 
*Restart
 
*Edit Parameters
 
*Edit Log File
 
 
 
=== Global Variables and Application State ===
 
Globals are often disparaged, in part because of strong coupling between components.  Nevertheless they are very useful in applications.  My approach is to use a class, never instantiated which is a singleton and which holds the global variables.  This is in a file called app_global.py, check out the ( very simple ) code there.  Objects that need to be globally available typically have an __init__
 
which contains a line much like  AppGlobal.a_global_reference = self.  It can then be accessed anywhere in the code ( after from app_global import AppGlobal ) as: a_useful_ref  = AppGlobal.a_global_reference.  Other application state information may be shared in an object of the class AppState.  Not quite sure how these differ form AppGlobals, maybe they doe not ( although I usually use an instance of this not the class itself ).  All this works fine, so I am using it this way now, but I need to think more about the proper way to code this stuff.
 
  
 
=== MultiThreading ===
 
=== MultiThreading ===
Line 95: Line 73:
 
I usually implement the standard python logging utility, messages into a file configured by parameters.py, the gui typically has a button to view this file.
 
I usually implement the standard python logging utility, messages into a file configured by parameters.py, the gui typically has a button to view this file.
  
= Links =
+
== Links ==
=== Projects Using these Conventions ===
+
 
*[[Python Control of Smart Plugs]]
+
 
*[[Python Smart Terminal]]
 
*[[Python Smart Terminal Graph]]
 
=== Other Links ===
 
*Use wiki feature "What Links Here".
 
 
*[[Configuration Files For Python]]
 
*[[Configuration Files For Python]]
*Look at the categories below.
+
*[[Configuration Files For Python]]
+
 
  
 
      
 
      
   [[Category:Python]][[Category:Python SmartPlug]] [[Category:Python Scheduling Application]][[Category:SmartTerminal]]
+
   [[Category:Python SmartPlug]][[Category:Python]]

Please note that all contributions to OpenCircuits may be edited, altered, or removed by other contributors. If you do not want your writing to be edited mercilessly, then do not submit it here.
You are also promising us that you wrote this yourself, or copied it from a public domain or similar free resource (see OpenCircuits:Copyrights for details). Do not submit copyrighted work without permission!

Cancel Editing help (opens in new window)