Software Engineering Lab 3
Clean code
1
Content
● Writing clean code in SEL3
● Scrum & communicating about project progress
2
Writing clean code in SEL3
3
“Indeed, the ratio of time spent reading versus writing is well over 10 to
1. We are constantly reading old code as part of the effort to write new
code. ...[Therefore,] making it easy to read makes it easier to write.”
Robert C. Martin, Clean Code:
A Handbook of Agile Software
Craftsmanship
4
You are responsible for clean code
5
6
Use intention-revealing names
● “One difference between a smart programmer and a professional programmer is
that the professional understands that clarity is king. Professionals use their powers
for good and write code that others can understand.” (Robert C. Martin - Clean Code)
● Names are everywhere in software, better do it good
● Good naming is hard, take your time!
● Be consistent in names (e.g. fetch_data vs load_data)
7
Use intention-revealing names
int elapsedTime
vs
int elapsedTimeInHours
def next_step(time, velocity, delta)
vs
def get_next_velocity(current_time,
current_velocity,
delta_time)
class Metrics
vs
class PerformanceMetrics
8
Use intention-revealing names
list1 = []
for x in input_list:
list1.append(x.perf)
vs
performance_per_epoch = []
for metrics in metrics_per_epoch:
performance_per_epoch.append(metrics.performance)
(or, alternatively)
performance_per_epoch = [metrics.performance for metrics in metrics_per_epoch]
9
Functions
● Smaller is better
● Functions should do only one thing (this is harder than it sounds)
● Use intention-revealing names
● Don’t be afraid to use long names. A long descriptive name is better than a short
name with comment.
● Keep the number of arguments to a minimum
● Avoid flags in arguments
● “Master programmers think of systems as stories to be told rather than programs to
be written.” (Robert C. Martin)
10
Compare this code fragment with …
void SetupRobot(){
foreach (GameObject go in gameObjects){
if (go.name.Contains("robot")){
ArticulationBody[] articulations = go.GetComponents(typeof(ArticulationBody)) as ArticulationBody[];
foreach (ArticulationBody articulationBody in articulations){
ArticulationDrive xDrive = articulationBody.xDrive;
xDrive.stiffness = 10000;
articulationBody.xDrive = xDrive;
}
}
}
}
11
… this fragment
void MakeAllRobotsStiff(float stiffness){
List<GameObject> robots = GetAllRobots();
SetAllJointsToStiffness(robots, stiffness);
}
List<GameObject> GetAllRobots(){
List<GameObject> robots = new ArrayList<GameObject>();
foreach (GameObject go in gameObjects){
if (go.name.Contains("robot")){
robots.Add(go);
}
}
return robots;
}
void SetAllJointsToStiffness(List<GameObject> robots, float stiffness){
ArticulationBody[] articulationBodies = FindAllArticulations(robots)
SetStiffnessOfAllArticulations(articulationBodies)
}
void FindAllArticulations(List<GameObject> robots){
12
… (encapsulate foreach loop)}
The best comment …
Is no comment
“The proper use of comments is to compensate for our failure to express ourself in
code.” (Robert C. Martin - Clean Code)
13
What makes a bad comment
● Comments that can be removed with expressive code
● Commented-out code
○ You are using source control, don’t do this. Just delete it.
● To explain variables
● Redundant comments
# this method loads the data from the specified directory
def load_data(data_path: str):
...
14
Avoiding comments with good code
Example:
# check whether agent is done training
if agent.is_training and agent.nr_epochs > max_epochs
Vs
if agent_is_done_training(agent)
15
What makes a good comment?
● API documentation
● Physical quantities
○ E.g. float angular_velocity = 1.0f; # in [radians s^-1]
● Clarifications, hacks
● TODO’s
● Warnings
16
Follow a style guide
● Choose as a team which coding convention you will follow
○ Google has naming conventions: https://google.github.io/styleguide/
○ MS: https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/inside-a-program/coding-
conventions
● Choose one, and be consistent
● Use code analysis tools
● Force style guide with build tools (e.g. pre-commit hooks with flake8, black, isort …)
17
Using version control systems (GIT)
● Commits are related to one piece of functionality
● .gitignore
● No data files in git
○ Trained models
○ Large datasets (pre-commit hook check-added-large-files)
● Git Large File Storage to track large files with Git, while keeping them out of your
actual repository
● Branches
○ main: deploy this
○ dev: push and merge all code here first
18
Project workflow tips
● Work on a fixed version (tag or release) of external libraries
● Follow directory standards when available
● Push stable releases to main branch, develop on develop branch
● Configuration system (txt, json, gin or other frameworks)
● Use Continuous Integration-tools (github actions, Jenkins, pre-commit, …) to enforce
build and code quality
20
Project documentation
● Documentation should flow out of the code
● Tools
○ Doxygen
○ Readthedocs
○ …
● README.md on github as entrypoint for external parties (in this case, this is us)
21
Undiscussed topics
● Exception handling
● Testing (unit and integration)
● Concurrency
● System building
● The use of null
● Language-specific best practices
22
Clean code in practice
To write clean code,
you first write dirty and
then clean up.
23
Scrum in SEL3
24
Scrum in SEL3
● Weekly sprints
● Scrum & consult session every week
● Questions
○ What have you done?
○ Where are you stuck?
○ What will you do the next week?
● Use any communication medium you want or need
25
Communication
26
Communication
27
What to do if you have (technical) questions?
1. LMGTFY
2. GitHub docs & issue tracker
3. Ufora & speak to each other
4. Consult sessions
5. [email protected] (start subject line with ‘[SEL3]’)
28
