Coding style

[ssinhaleite]

To integrate all the SynSense software, we need to define our style guide.

Do we follow the Google style or Pep 8 for documentation? Do we define our own?
We should double-check what we have been doing in Rockpool as well.

Where do you add docstrings: class definition or init method? Is it a good practice to use both?
Do we use Args or Parameters as tags?

Is our convention straightforward to add to black or other automated formatter?

Do we add PyLint to our coding best practices?

Check on error messages and use of a log system.

Handling code TODOs: every TODO should contain a) a deadline and b) an associated issue (should be mentioned in the code).

Do you have any thoughts/comments/suggestions?

[DylanMuir]

• For docstrings we mostly follow google style I believe, rather than PEP8/numpy. We should stick with one and use it consistently.
• Best practice is to have docstrings for both class definition and __init__. But class definition does not need the init arguments.
• We should impose black formatting, either as a post-commit hook or a merge test (as in Rockpool)
• PyLint is helpful, but I think we shouldn't impose this at this point
• Agree about TODOs, these are helpful if they link to issues

[MinaKh]

About including a deadline in Issues and ToDos:
Soon we should be able to assign and track our SW To Do s with Wrike and then we will have deadlines there.

[ssinhaleite]

In my opinion, deadlines in the TODOs are not to track work.
TODOs are already a "code smell," an indicator that something was not considered before or is not a priority now.
A TODO deadline can be simple: "TODO by release X" or "TODO by release of library Y."
This deadline comes from the developer, who recommends when this should be done. The deadlines from Wrike are general deadlines for project management, and they might not match if the Product Owner has other plans in terms of delivery and feature priorities.

[MinaKh]

Yes, they can be agreed between developer and product owner :)

[ssinhaleite]

We defined our code style guide, and I am attaching the PDF with the Python Style Guide.
Python-Style-Guide.pdf