






























Study with the several resources on Docsity
Earn points by helping other students or get them with a premium plan
Prepare for your exams
Study with the several resources on Docsity
Earn points to download
Earn points by helping other students or get them with a premium plan
Community
Ask the community for help and clear up your study doubts
Discover the best universities in your country according to Docsity users
Free resources
Download our free guides on studying techniques, anxiety management strategies, and thesis advice from Docsity tutors
Guidelines for refactoring code, variable naming and access, readability, commenting and documentation, black-box testing, and const/reference in programming. It emphasizes the importance of consistency, simplicity, and avoiding redundancy and deep nesting. The document also discusses the use of commenting and documentation tools such as Sphinx, EpyDoc, and PythonDoc.
What you will learn
Typology: Study notes
1 / 38
This page cannot be seen from the preview
Don't miss anything!
โ Code Refactoring โ Variable Naming and Access โ Tips for Readability โ Commenting and Documentation โ Black-Box Testing โ Const/Reference
โ Rewriting code for clarity, not bug fixing. Similar to writing paper drafts
โ Rewrites may include: โ Documentation / Comments โ Change in Flow โ Variable Naming Conventions โ Creation of Functions / Classes โ Simplification โ Eliminating Duplicate Code โ Re-usable
โ camelCase ballRadius โ Underscore between words -> ball_radius at start (private/protected) -> _speed โ Uppercase for constants GRAVITY โ Capitalize first word for classes Person()
Eliminate redundancy in order to create more readable code
โ Too many operations per line is confusing to read
Use list comprehensions, filter(), and map() where applicable
Use enumerate to keep track of index and element values
โ Avoiding obvious comments
โ When possible, rewrite the code so no comments are necessary
โAt the beginning of every routine, it is helpful to provide standard, boilerplate comments, indicating the routines purpose, assumptions, and limitations. A boilerplate comment should be a brief introduction to understand why the routine exists and what it can do." https://msdn.microsoft.com/en-us/library/aa260844(v=vs.60).aspx
โ Sphinx โ http://www.sphinx-doc.org/en/stable/index.html โ http://www.sphinx-doc.org/en/stable/ext/example_google.html
โ EpyDoc โ http://epydoc.sourceforge.net
โ PythonDoc โ http://effbot.org/zone/pythondoc.htm#syntax
โ Given a function, you know what the output should be for given inputs โ Select cases which cover all typically expected behavior โ Software can verify function still works by running these tests
โ DocTest โ https://en.wikipedia.org/wiki/Doctest