# Software WG taskforce: software development guidelines

Meeting 1: Wed 2 Nov, 1700 UTC

- https://github.com/OCNS/SoftwareWG/issues/116
- https://github.com/OCNS/SoftwareWG/issues/113
- https://github.com/OCNS/SoftwareDevelopmentGuidelines

# Attendees

- Ankur Sinha (UCL: Software WG, Open Source Brain, NeuroML etc. `ankur.sinha AT ucl DOT ac DOT uk`)
- Anil
- Chitranjan

# Chairs

- Anil
- Chitranjan

## Chair responsibilities:

- sending meeting reminders
- running meetings
- being general points of contact for the task force
- liasing with other related communities (such as the Software WG that we are part of)

# Communication

- Async communication via the GitHub ticket for the time being: https://github.com/OCNS/SoftwareWG/issues/116

# Notes

- Next meeting in ~2 weeks, week starting November 14
- ACTION: Chitranjan set up new doodle for next meeting

## Pre-existing resources:

Collected in tickets on the GitHub repository: https://github.com/OCNS/SoftwareDevelopmentGuidelines/issues

A number of resources already exist:

- [CODECHECK community workflow guide | CODECHECK](https://codecheck.org.uk/guide/community-workflow)
- [Python Best Practices — Python Best Practices 0.3.0 documentation](https://python-best-practices-software-that-just-works.readthedocs.io/en/latest/)
- [Guide for Reproducible Research — The Turing Way](https://the-turing-way.netlify.app/reproducible-research/reproducible-research.html)
- [Best Practices for Scientific Computing | PLOS Biology](https://journals.plos.org/plosbiology/article?id=10.1371/journal.pbio.1001745)
- [Good enough practices in scientific computing | PLOS Computational Biology](https://journals.plos.org/ploscompbiol/article?id=10.1371/journal.pcbi.1005510)
- [Research Software - Tag](https://rseng.github.io/rseng/tag/)
- [Guides | Software Sustainability Institute](https://software.ac.uk/guides)
- [BadgeApp](https://bestpractices.coreinfrastructure.org/en)
- [Google Style Guides | styleguide](https://google.github.io/styleguide/)
- [PSIP](https://rateyourproject.org/)

## Question: do we need another resource (scope of the task force)?

Yes:

- current resources are too complex?
- a "short sweet" list of items would be beneficial to the community

No:

- current resources are enough, but the issue is limited uptake

ACTION: task force members go through resources to make example lists of what items they think would be useful. The idea is to go through the lists to see why they are insufficient (if they are insufficient), and to come up with individual lists of items that we will compare in the next meeting.

# Lists

## Ankur's list

(noting in another doc, will paste here before meeting)

## Anıl's list

* Consistent code style reduces the cognitive load.
* Static code analysis tools can detect bugs before runtime.
* https://docs.sourcery.ai/Reference/Built-in-Rules/suggestions/default-mutable-arg/
* https://rules.sonarsource.com/python/RSPEC-5717
* Data structures knowledge is important.
* Avoid mutability whereever possible.
* If a variable does not change, make it immutable.

### Arnaoudova's Linguistic Antipatterns
* Methods that do more than they say
* Methods that say more than they do
* Methods that do the opposite of what they say
* Identifiers whose names say that they contain more than what the entity contains
* Identifiers whose names say that they contain less than what the entity contains
* Identifiers whose names say the opposite of what the entity contains

Arnaoudova, Venera, et al. "A new family of software anti-patterns: Linguistic anti-patterns." 2013 17th European Conference on Software Maintenance and Reengineering. IEEE, 2013.

### Kent Beck's Code Smells
Code smells, such as long methods, indicate
structural issues with code. There are different
cognitive reasons why code smells cause a higher
cognitive load.

### CWE Top Most Dangerous Software Weaknesses
This list mainly focuses on security but the issues listed there correlate with various other design problems.
https://cwe.mitre.org/top25/archive/2022/2022_cwe_top25.html#cwe_top_25

### Books to read on the matter
* Refactoring 2nd Edition, Martin Fowler
* Clean Code, Robert Martin
* Programmer's Brain, Felienne Hermans