CSCI 494-802: Industry Methods

2/25/2025

Clean Code, Code Review

Agenda

• Attendance
• Questions on Assignment 3?
• Clean Code
• Code Review Tips

Attendance

Questions?

Any questions about Assignment 3?

Please do not merge the branch yet

• if you have already done this, no worries we can revert / rebuild it

Feedback

Push yourself out of your comfort zone

If python is your strongest language, try a different one for these easy problems.

​

As inspiration this individual solved the first 100 project euler problems with 100 different languages

https://github.com/jaredkrinke/100-languages

​

READ 10x more code than you write...

Clean Code

• Simplify naming, commenting, and formatting with tips that apply to every line of code
• Refine your program’s loops, logic, and variables to reduce complexity and confusion
• Attack problems at the function level, such as reorganizing blocks of code to do one task at a time
• Write effective test code that is thorough and concise—as well as readable

​

Clean Code

Take pride in your work

​

“Leave the campground cleaner than you found it”

​

“Presentation is as important as the quality of the content that you are presenting”

​

"Any fool can write code that a computer can understand. Good programmers write code that humans can understand."

Summary - Clean Code

• KISS
• Boy Scout Rule
• Prefer polymorphism to if/else or switch/case.
• Law of Demeter
• Use explanatory variables.
• Choose descriptive and unambiguous names.
• magic numbers << named constants
• Don't comment out code. Just remove.
• ...

Functions rules

• Small.
• Do one thing.
• Use descriptive names.
• Prefer fewer arguments.
• Have no side effects.
• Don't use flag arguments. Split method into several independent methods that can be called from the client without the flag.

​

More Book Recommendations

• Clean Code: A Handbook of Agile Software Craftsmanship by Robert C. Martin
• Design of Existing Code by Martin Fowler
• The Pragmatic Programmer: Your Journey To Mastery by David Thomas
• Grokking Simplicity - Eric Normand
• Code Complete: A Practical Handbook of Software Construction by Steve McConnell

10 Clean Code Techniques

1. Keep it Simple
2. Understand Your Code
3. Comments are your new best friends
4. Don’t Repeat Yourself (DRY)
5. Indent Your Code
6. Naming Convention
7. Explore
8. Use Your Brain
9. Test Runs
10. Practice Your Art

Naming Variables

"A name should tell you why it exists, what it does, and how it is used. If a name requires a comment, then the name does not reveal its intent."

– Clean Code

​

“Take as much time as you would naming your first born child” - unknown internet

Clean Code Explained - Name Variables

• Create Meaningful Names
• Avoid Disinformation
• Avoid Noise Words
• Use Pronounceable Names
• Use Searchable Names
• Be Consistent

Clean Code Explained - Write Functions

• Keep them Small
• Make Sure They Just Do One Thing
• Encapsulate Conditionals in Functions
• Fewer Arguments (2 or fewer)
• Do not use Flag Arguments
• Do Not Have Side Effects
• Don’t Repeat Yourself

Additional Examples from ChatGPT

I Shall Call It... SomethingManager

1. Describe everything the routine does
2. Avoid meaningless, vague, or wishy-washy verbs
3. Don’t differentiate routine names solely by number
4. Make names as long as necessary
5. For functions, try using a description of the return value
6. Use opposites precisely
7. Establish conventions for common operations

​

More Benefits and Tips

The benefits of writing clean code

1. Easier to start, or continue

2. Better for team onboarding

3. Easier to follow

​

Tips on writing clean code

1. Make code readable for people

2. Use meaningful names for variables, functions and methods

3. Let one function or method perform only one task

4. Use comments for clarification

5. Be consistent

6. Review your code regularly

​

Want Cleaner Code? Use the Rule of Six

• Every line does only one thing
• It's not all about line length
• The Rule of Six: A line of code containing 6+ pieces of information should be simplified.
• If code is confusing, break it

Other Views

There’s No Such Thing as Clean Code

“Coding is generally a team sport”

​

Forget about Clean Code, let's embrace Compassionate Code

​

More Tips

9 Clean Code Patterns I wish I knew earlier | by Martin Thoma | Towards Data Science

​

​

Line of sight in code: Left edge is happy path, indented is error handling and edge cases

Code: Align the happy path to the left edge | by Mat Ryer | Medium

example: polymorphism over an if/else statement

Clean code summarized

Write small blocks of code

Small functions, small classes, small modules.

​

It will result in:

​

- higher cohesion

- better maintainability

- modular code structure

- ability to capture domain knowledge

- compliance with Single Responsibility Principle

​

And the improved readability will make your future self and your colleagues happier.

Clean Architecture

Ports and Adapters

A Brief Intro to Clean Architecture, Clean DDD, and CQRS - Software Alchemy

No Code

https://github.com/kelseyhightower/nocode

Clean Code Funny

Code Review (+1, +10)

Much of your day as a programmer will involve reviewing other pull requests and providing valuable feedback

​

Auditable

SOC1, SOC2, ...

+1

+1 is an acknowledgement of a code review

• in the past this was just a comment left somewhere in the PR thread

​

Github has a nice Code Review feature directly - DEMO

What do you look for during a +1?

• Does it solve the problem?
• Is it clean? simple? documented?
• Does it adhere to code style guide?
• Does it contain tests?

The Code Review Pyramid - Gunnar Morling

​

​

Tact

Always remember:

• Use Professionalism
• Practice Egoless Programming

10 Commandments of Egoless

The Ten Commandments of Egoless Programming

​

Code Review tips

::..: glen.nu :.: ramblings :.: on code review :.::

Google Testing Blog: Code Health: Understanding Code In Review

Best Practices for Peer Code Review

Effective Code Review Tips

​

More code review tips

Google Testing Blog: Code Health: Understanding Code In Review

​

Code Reviews: The Definitive Guide - Simple Programmer

​

​

More Guidelines

Code Review Guidelines for Data Science Teams — tdhopper.com

​

^^ Friend of my co-worker!

Style Guides

a set of conventions (sometimes arbitrary) about how to write code for that project. It is much easier to understand a large codebase when all the code in it is in a consistent style.

​

​

http://google.github.io/styleguide/

https://javascript.info/coding-style

​

​

Google Engineering Tips

How to do a code review...

​

Conventional Commits / Comments

Conventional Comments

Conventional Commits

​

​

Automate Style Rules

Lint - https://en.wikipedia.org/wiki/Lint_(software)

​

Static Code Analysis -

https://en.wikipedia.org/wiki/List_of_tools_for_static_code_analysis

Cyclomatic Complexity

Cyclomatic complexity is a software metric used to indicate the complexity of a program. It is a quantitative measure of the number of linearly independent paths through a program's source code. It was developed by Thomas J. McCabe, Sr. in 1976.

Cyclomatic Complexity

Why is it important?

• Limit code complexity.
• Determine the number of test cases required.

​

What Is Cyclomatic Complexity? | Perforce�

Cyclomatic Complexity

Use the following formula to calculate cyclomatic complexity (CYC):

CYC = E – N + 2P

​

P = number of disconnected parts of the flow graph (e.g. a calling program and a subroutine)

E = number of edges (transfers of control)

N = number of nodes (sequential group of statements containing only one transfer of control)

​

More on CYC

What is Cyclomatic Complexity - Learn with an Example

​

Cyclomatic Complexity in Software Testing (Example)

​

​

Metrics Study

Program Comprehension and Code Complexity Metrics: An fMRI Study

​

Code Coverage

Tools exist to measure the lines of code that are covered by tests. Some companies require a certain threshold of testing (e.g. 75% of lines covered) with every pull request, otherwise the build fails.

​

codecov is an example

+10

+10 is a sanity check that another developer can checkout and run the code

​

This is not a full regression test but an assurance that the code in question passes a minimal test on a separate developer’s machine

​

Keep the local dev story working...

Capture Output

• Capture a screencast if it involves UI
• Capture a screen output if it involves cmdline
• Stash logs

​

Attach these artifacts to any review. Be as verbose as possible, but be careful of logging PII (Personally Identifiable Information).

Questions?