Tamas Gal (ECAP)
https://indico.in2p3.fr/event/21698/contributions/84479
Workshop for Open-Source Software Lifecycles
2020-07-24 - Zoom
This talk sheds light on a few things to think about when developing code. It’s OK if you say “Why certainly!” every other slide. These are things which need to be spoken out to have an actual impact.
Everyone of us would came up with the same ideas after thinking about them proactively.
Any similarities to persons living or dead, or actual events are purely intentional.
tamasgal on GitHub/GitLab/Twitter)Serves multiple purposes:
“Indeed, the ratio of time spent reading versus writing is well over 10 to 1. We are constantly reading old code as part of the effort to write new code. …[Therefore,] making it easy to read makes it easier to write.”
– Robert C. Martin, Clean Code: A Handbook of Agile Software Craftsmanship
delapsed_time_in_daysel<TAB>Don’t comment obvious things. Try to express yourself through code.
def read_humidities(sensors): "Auxiliary function to read the humidities from multiple sensors" data = [] # list to store the humidities n = len(sensors) # number of sensors for i in range(n): value = sensor.read() data.append(value) return data # return a list of humidities
def read_humidities(sensors): "Read the humidity from multiple sensors" return [sensor.read() for sensor in sensors]
# Matches the UTC format YYYY-MM-DDThh:mm:ssZ match(r"^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z$", datetime)
34432 case 342: 34433 calib[341] = "/pmt_342.dat" 34434 break; 34435 case 343: 34436 calib[342] = "/pmt_343.dat" 34437 break; 34438 case 344: 34439 calib[343] = "/pnt_344.dat" 34440 break; 34441 case 345: 34442 calib[344] = "/pmt_345.dat" 34443 break;
def calibrate(fname, d, phi, gamma, pos_x, pos_y, pos_z, n, max_n, start_at, wait_until, n_iterations=1000, panic=True, answer=42, hi="mom")
def calibrate(fname, params: CalibParams, opts: CalibOptions)
Using type hinting in Python and extra classes CalibParams and CalibOptions which take care of further documentation, error checking and default values.
Leave the code better than you found it
Try to increase the code test coverage with each commit (see Level 2)
Makefile to create one-word commands to run a set of tasksmake test vs py.test --junitxml=reports/junit.xml -o junit_suite_name=main the_modulemake install-dev)
Makefileinstall: pip install . install-dev: pip install -r requirements.txt pip install -r requirements-dev.txt pip install -e . test: py.test --junitxml=./reports/junit.xml -o junit_suite_name=$(PKGNAME) tests test-cov: py.test --cov ./km3io --cov-report term-missing --cov-report xml:reports/coverage.xml --cov-report html:reports/coverage tests test-loop: py.test tests ptw --ext=.py,.pyx --ignore=doc tests
@testset "binomial" begin @test binomial(5,-1) == 0 @test binomial(5,10) == 0 @test binomial(5,3) == 10 @test binomial(2,1) == 2 @test binomial(1,2) == 0 @test binomial(-2,1) == -2 # let's agree @test binomial(2,-1) == 0 #Issue 6154 @test binomial(Int32(34), Int32(15)) == binomial(BigInt(34), BigInt(15)) == 1855967520 @test binomial(Int64(67), Int64(29)) == binomial(BigInt(67), BigInt(29)) == 7886597962249166160 @test binomial(Int128(131), Int128(62)) == binomial(BigInt(131), BigInt(62)) == 157311720980559117816198361912717812000 @test_throws OverflowError binomial(Int64(67), Int64(30)) end
“An application programming interface (API) is a computing interface which defines interactions between multiple software intermediaries.”
– Fisher, Sharon (1989). “OS/2 EE to Get 3270 Interface Early
public API and private API
Once you push your code to a public repository, there is a chance that code is created which immediately depends on your public API
Every time you change the public API, you will potentially break existing code.
julia> findn([1,0,3]) ┌ Warning: `findn(x::AbstractVector)` is deprecated, use `(findall(!iszero, x),)` instead. │ caller = top-level scope at none:0 └ @ Core none:0 ([1, 3],)
Given a version number MAJOR. MINOR. PATCH, increment the:
The user will typically fall from the sky and crash through the layers from top to bottom.
GitHub Actions, GitLab CI, Travis, Jenkins, AppVeyor, …
Bug your local system administrator if you don’t have such a system running at your institute. A typical Linux nerd can roll off a very basic CI platform within a few days.
.gitlab-ci.yml)build:
script:
pip install .
Makefile can be used to outsorce tasksCONTRIBUTING.md)CITATION or alike and consider writing a JOSS paper