Good Programming Practices
Andrew Showers, Salles Viana
ALAC
Overview
● Code Refactoring
● Variable Naming and Access
● Tips for Readability
● Commenting and Documentation
● Black-Box Testing
● Const/Reference
Disclaimer
A style guide is about consistency and improving readability of code.
Know when to be inconsistent, guidelines will serve as a rule of thumb and not an
absolute. Ask yourself if the rules being applied make the code more readable.
Code Refactoring
● 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
Variable Naming Conventions
● camelCase
ballRadius
● Underscore
between words -> ball_radius
at start (private/protected) -> _speed
● Uppercase for constants
GRAVITY
● Capitalize first word for classes
Person()
Variable Access
● Avoid global variables unless it drastically simplifies code
○ Use your intuition. If the variable is used throughout the entire program, global is probably fine
● Avoid public variables for classes. Enforce the idea of encapsulation
○ Instead of public variables, create getters and setters
Avoid Redundant Labeling
Eliminate redundancy in order to create more readable code
VS
Avoid Deep Nesting
VS
Avoid Explicit Comparisons (when possible)
https://docs.python.org/3/library/stdtypes.html#truth-value-testing
VS
Avoid Long Lines
● Too many operations per line is confusing to read
VS
One Statement per Line
VS
Strive for Simplicity
Code should be explicit and straightforward
VS
Strive for Simplicity (cont.)
Use list comprehensions, filter(), and map() where applicable
VS
VS
Strive for Simplicity (cont.)
Use enumerate to keep track of index and element values
VS
Commenting
● Explain logic in a clear and understandable manner
○ Avoid jargon when possible
○ Aim for explanation to be understood by non-programmers
● Spacing and logical grouping
○ Parsing data
○ Solving a particular subproblem
○ Displaying results
● Keep them up to date
○ Outdated comments lead to more confusion
Commenting (cont.)
● Avoiding obvious comments
● When possible, rewrite the code so no comments are necessary
VS
Commenting (cont.)
“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
Examples of function boilerplate:
Documentation
● 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
Black-Box Testing
● 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
Avoid Convoluted Tricks
Just because you can doesn't mean you should
Examples:
● change how objects are created and instantiated
● change how the Python interpreter imports modules
● embedding C routines in Python
Exceptions exist, ask yourself if it is absolutely necessary (such as performance)
Some common mistakes seen in DS homeworks
Some of these problems may also apply to CS-1
Not using local variables properly
● Even local variables may be “too global”
● Try to avoid declaring variables too soon
What is the problem with the following example?
● Common cause: Ctrl-C + Ctrl-V
Not using local variables properly
Ok now?
Another common mistake...
Another common mistake...
Const/reference
Ok now?
Const/reference
getName() → always returns a COPY of name…
Const/reference
Ok now?
Const/reference
Where does the compilation error happen? What if getName() was not const?
Const/reference
Const returned value: you Const function:
can’t modify the returned - Can’t modify object.
reference. - → can be applied to a const object
Reference: does not copy
the returned value
This function should
Const/reference be in the .cpp file !
Const/reference
[i]
Code reuse
Avoid having duplicate code
● More code → more bugs (usually)
● More code → more things to fix
● More code → more time to implement
● More code → lower grade!
What is the problem here?
Typo: missing a * →
will have to fix here
AND in the
constructor...
Matrix a(5,2);
Matrix b(3,3);
a = b; //the operator will call a.copy(b)
● Smaller code
● Easier to read
Now we only
have to fix the
typo here...
References
PEP 8 -- Style Guide for Python Code:
https://www.python.org/dev/peps/pep-0008/
The Best of the Best Practices (BOBP) Guide for Python:
https://gist.github.com/sloria/7001839
Coding Techniques and Programming Practices:
https://msdn.microsoft.com/en-us/library/aa260844(v=vs.60).aspx
Code Style http://docs.python-guide.org/en/latest/writing/style/
