write-readable-code
how to write a code that is readable and reusable
https://github.com/carpentries-incubator/write-readable-code
Science Score: 54.0%
This score indicates how likely this project is to be science-related based on various indicators:
-
✓CITATION.cff file
Found CITATION.cff file -
✓codemeta.json file
Found codemeta.json file -
✓.zenodo.json file
Found .zenodo.json file -
○DOI references
-
○Academic publication links
-
✓Committers with academic emails
1 of 2 committers (50.0%) from academic institutions -
○Institutional organization owner
-
○JOSS paper metadata
-
○Scientific vocabulary similarity
Low similarity (14.2%) to scientific vocabulary
Keywords
Repository
how to write a code that is readable and reusable
Basic Info
- Host: GitHub
- Owner: carpentries-incubator
- License: other
- Language: Python
- Default Branch: main
- Homepage: https://carpentries-incubator.github.io/write-readable-code/
- Size: 8.3 MB
Statistics
- Stars: 0
- Watchers: 2
- Forks: 0
- Open Issues: 0
- Releases: 0
Topics
Metadata Files
README.md
Writing Readable Code
This course is intended for scientists with a basic to intermediate understanding of Python who wish to improve the quality of their code. Although Python is used as an example language, the general concepts can be applied to other languages.
There are a few misconceptions that this course aims to correct:
"I will always remember my code": The idea is that since I wrote the code, I will always be able to explain it to others. The reality is different. When a code is completed, used once or for a limited time, even the author will forget how it works or what it does. Therefore, when it is needed to be reused in the future, a lot of time is wasted trying to understand it. If the code is written, keeping in mind that we need to reuse it, we can write better code that requires less time to read.
"Code is for the computer to run". True, but also for people to read. Code is often more read than written. We read code when trying to modify it or add new features. If someone else wrote the codebase, we spent more time reading it and trying to understand how it works than writing new code to extend it. Creating a code for people will make it easy to read and maintain. This results in spending less time trying to understand the code.
"Software engineers write good code. I am a scientist, I don't need to". Scientists use code for their research, and even if it is not their main outcome, code is sometimes the primary tool to reproduce the results. Often, they share their code with a large community so that other people can use it. If the code is not clear, not tested and not easy to extend, it cannot be easily used. Therefore, scientists must invest time in writing good-quality code.
"I don't have time for testing". Testing is the most underrated task in any coding activity. Design and writing tests require time, and although some testing is added to evaluate the code, coding projects often lack a reliable testing framework. The truth is testing can actually save time in the long run. Every time a code needs to be improved or extended, a test will be required to ensure that any change did not affect previous functionality. Testing also provides trust in the code and, therefore, in the results it produces.
Course Links
Please have a look at the content here
Lesson Status
The course is in pre-alpha.
Course Design
The course is divided into four episodes:
- Episode 1: Write Readable Code
- Episode 2: Write Elegant Code
- Episode 3: Write Graceful Code
- Episode 4: Write Reliable Code
Each episode combines discussion and hands-on activities
Course Delivery
The course is suitable for both instructor-led teaching and self-learning.
Enviroment
The course does not use and require any specific version of Python or packages, but it uses the following
- numpy
- matplotlib
- Pytest
The setup used for this course is: -Python 3.13.1 - numpy==2.2.4 - matplotlib==3.10.1 - pytest==8.3.5
Contributions
All contributions to improve the lesson are welcome!
If you wish to contribute, please familiarise yourself with Contribution Guide and have a look at the detailed guidelines on proper formatting, instructions on compiling and rendering the lesson locally, and making any changes and adding new content or episodes.
Author
Magda Guglielmo, CSIRO
Maintener
Magda Guglielmo, CSIRO
Owner
- Name: carpentries-incubator
- Login: carpentries-incubator
- Kind: organization
- Repositories: 107
- Profile: https://github.com/carpentries-incubator
Citation (CITATION.cff)
# This template CITATION.cff file was generated with cffinit.
# Visit https://bit.ly/cffinit to replace its contents
# with information about your lesson.
# Remember to update this file periodically,
# ensuring that the author list and other fields remain accurate.
cff-version: 1.2.0
title: Write readable code
message: >-
Please cite this lesson using the information in this file
when you refer to it in publications, and/or if you
re-use, adapt, or expand on the content in your own
training material.
type: dataset
authors:
- given-names: Magda
family-names: Guglielmo
affiliation: CSIRO
email: magda.guglielmo@csiro.au
abstract: >-
This lesson introduces the importance of writing readable code, highlighting that this practice primarily benefits the author before aiding others.
Participants will explore examples of basic, functional, yet unstructured code and learn to apply simple rules—such as meaningful names, effective
error handling, and clear docstrings—that transform it into readable and maintainable scripts. This approach has the advantage of making code easier
to understand, debug, and improve.
The lesson also emphasises the importance of testing and its role in making the code more reliable.
By being introduced to test-driven development (TDD), learners will discover how creating tests before can lead to more robust and structured code.
By the end of the lesson, participants will be equipped with practical techniques to improve their coding standards.
They will understand how to inspect their code critically to continuously improve its quality.
license: CC-BY-4.0
GitHub Events
Total
- Issue comment event: 1
- Push event: 31
- Pull request review event: 1
- Pull request event: 2
- Create event: 1
Last Year
- Issue comment event: 1
- Push event: 31
- Pull request review event: 1
- Pull request event: 2
- Create event: 1
Committers
Last synced: 9 months ago
Top Committers
| Name | Commits | |
|---|---|---|
| Magda Guglielmo | m****o@c****u | 12 |
| MagdaG81 | M****1 | 1 |
Committer Domains (Top 20 + Academic)
Issues and Pull Requests
Last synced: 9 months ago
All Time
- Total issues: 0
- Total pull requests: 1
- Average time to close issues: N/A
- Average time to close pull requests: about 3 hours
- Total issue authors: 0
- Total pull request authors: 1
- Average comments per issue: 0
- Average comments per pull request: 1.0
- Merged pull requests: 1
- Bot issues: 0
- Bot pull requests: 0
Past Year
- Issues: 0
- Pull requests: 1
- Average time to close issues: N/A
- Average time to close pull requests: about 3 hours
- Issue authors: 0
- Pull request authors: 1
- Average comments per issue: 0
- Average comments per pull request: 1.0
- Merged pull requests: 1
- Bot issues: 0
- Bot pull requests: 0
Top Authors
Issue Authors
Pull Request Authors
- carpentries-bot (2)