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 {** * Code Readability ef if (readable()) { be_happy(); } else { refactor(); } Overview ● Code Refactoring ● Variable Naming and Access ● Tips for Readability ● Commenting and Documentation ● Black-Box Testing ● Const/Reference 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 VS Eliminate redundancy in order to create more readable code Avoid Long Lines ● Too many operations per line is confusing to read VS One Statement per Line print('one"); print(‘two') if x == 1: print(‘one') if <complex comparison> and <other complex comparison>: # do something Vs print(‘one') print(‘two') if x == 1: print(‘one') cond1 = <complex comparison> cond2 = <other complex comparison> if cond1 and cond2: # do something Strive for Simplicity Code should be explicit and straightforward 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 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 Th ie Wea (1=0;1<n; i++) numbers[i] = 0; (j=0; <n; j++) numbers2[i] = 0; int i,j; (i=0;i<n;i++) numbers[i] = 0; (j=0; j<n; i++) numbers2[j] = 0; (int i=0;i<n;i++) numbers[i] = 0; (int j=0;j<n; j++) numbers2[i] = 0; Cheek eee) numbers[i] = 0; (int j=0;j<n;i++) numbers2[i] = 0; Another common mistake... Person { public: string getName() { return name; a oy aa string name; 1 oid print(Person p) { cout << p.getName() << endl; } Another common mistake... Person { public: string getName() { mame DO tte] N= i fo) ae =a ae a em T= 11a ti foid print(const Person &p) { cout << p.getName() << end1; } Const/reference Ok now? 5 Person { string & c () } Ue string name; Const/reference Where does the compilation error happen? What if getName() was not const? Const/reference Const function: - Can’t modify object. - → can be applied to a const object Reference: does not copy the returned value Const returned value: you can’t modify the returned reference. 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! Matrix a(5,2); Matrix b(3,3); a = b; //the operator will call a.copy(b) What is the problem here? Typo: missing a * → will have to fix here AND in the constructor... ● Smaller code ● Easier to read Now we only have to fix the typo here...