Commenting notes:

As well as making the code more readable, comments are also a useful tool for debugging.

Comments within code should be preceded with a hash # and can either be:

  • Block comments - apply to the code which follows them, are indented to reflect the code;

  • Or inline comments - a comment on the same line as the code, should be separated from the code by at least two spaces.

Further reading:

An interesting study by Rani et al. (2021) on the assessment of commenting conventions in programming languages, including Python – languages such as Python and Java ‘do not provide any default template to write comments but support multiple style guidelines for each project.’ Thus, comments in Python and other languages are ‘usually written in a semi-structured manner using natural language sentences’ and while there have been coding style guidelines implemented, these existing conventions lack the necessary quality and precision. These issues are important to consider when acknowledging the significance of implementing high quality and consistent commenting within programming.

Assignment 2 update:

During this unit, I focused on completing the code for the UML diagrams(use-case diagram, activity diagram and class diagram).

References

Reitz, K. (2016). The Hitchhiker’s Guide to Python: Best Practices for Development. O’Reilly.

Rani, P., Abukar, S., Stulova, N., Bergel, A. & O. Nierstrasz (2021). Do Comments follow Commenting Conventions? A Case Study in Java and Python. 2021 IEEE 21st International Working Conference on Source Code Analysis and Manipulation (SCAM). pp.165-169. DOI: 10.1109/SCAM52516.2021.00028.