Just curious, how do you guys format your comments to clearly separate and document your different functions within a project library script? I sometimes find it hard to pick out where the next
def is and wondering if anyone has a good solution, along with general formatting for function description comments.
Would be nice if there was a way for us to add comments that would show up as the "tooltip" when typing the function in a script, the same way the system functions do.
Newer versions do actually allow this using the doc string;
For instance, I have this script in a Library:
def getProcessingOccurences(hours = 23):
Returns: A list of the number of occrences by hour for the given number of hours.
paths = [historicalProvider + p for k,v in tagPaths['processing'].iteritems() for p in v['paths']]
thisHour = system.date.getHour24(system.date.now())
endDate = system.date.setTime(system.date.now(),thisHour,0,0)
startDate = system.date.addHours(endDate,-hours)
return system.tag.queryTagHistory(paths,startDate,endDate,aggregationMode = 'CountOn',returnFormat='Tall',columnNames = [path.replace(' ','_').split('/')[-1:] for path in paths],intervalHours = 1)
Then in the tool tip it looks like this:
If you're on 8.1.19 or higher, project library scripts with "docstrings" per Python convention do show up in the autocomplete in other editors:
If you're on 8.1.32 or higher, if you author those docstrings according to Google's Python style guide, you'll even get nice argument and return value descriptions.
So that answers one question.
What I've been doing to separate the
defs more clearly is using a full line of "#"
Do you have the Script Hint pane showing?
Is it not always at the bottom? If I need to move to a specific spot or want to go to a specific function I just use the sidebar of the project scripting double clicking a function takes me right to it-
The only other organization I do within project libraries - I always put all my business logic (database/tag writing stuff) towards the top, and then any callers of said functions from a GUI towards the bottom (same goes if this is logic called from message handlers - call and handler are at the bottom but any business logic all at the top grouped togeher)
Note that for any vision or perspective specific libraries (
system.perspective, etc)they should be called within the function or you'll risk issues depending where you call your script from.
Edit: Now that I think about it, as long as the function is only called from the right scope, I am not even sure
import system.gui/import system.perspective would be necessary. It's been a while since I wrote the above.
Not necessary. Doing
from system.something import * can be handy in some cases, but otherwise imports just slow your script.
(You still have to import jython stdlib modules. But only those.)