Good Programming Practices: A Style Guide for Writing Clear and Readable Code, Study notes of Logic

Download Good Programming Practices: A Style Guide for Writing Clear and Readable Code and more Study notes Logic in PDF only on Docsity!

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

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()

Avoid Redundant Labeling

VS

Eliminate redundancy in order to create more readable code

Avoid Deep Nesting

VS

Avoid Long Lines

● Too many operations per line is confusing to read

VS

One Statement per Line

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 (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

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