Coding a Better World Together with Uncle Bob

If you don't have the time to watch these lengthy videos on YouTube, this article is for you.

These are the summary of what I learned from all these "Coding a Better World Together" lessons from Uncle Bob in my own words. I only extract the information that is useful to me.

I added my comment in bold for those that I do not fully agree with him or anything that is significant to me.

Clean Code - Uncle Bob (Lesson 1)

• By nature, we don't write clean code. Solving the problem is the main priority. Thus, we need to refactor.

Function

• Keep function small, do one thing.
• One thing means you extract until you can can't do it anymore.
• Function should be properly named (tells what the function does)
• Function must be verb.
• Function should have less than 3 arguments.
• Don't pass Boolean into a function for branching purpose.
• Avoidswitch and if statement. Use polymorphism (open-closed principle).

Side Effects

• Side effect function changes the state of the system.
• Use lambda for side effect function that comes with pair (e.g. open a file, and close a file). Pass in processing callback implementation as lambda into a function.
• Convention to follow - command is a function that returns nothing, should have a side effects. Query is a function that returns value, should NOT have a side effect.
• Prefer exceptions to returning error codes. Try block should only content one function call which throws the exception. [I made this mistake. Most of my try block contains unnecessary stuff that can be pulled out.]

Others

• Don't Repeat Yourself, avoid duplicated code.
• Software is like science, which cannot be proven correct.

Clean Code - Uncle Bob (Lesson 2)

Comments

• Comment is to explain the code that you can't use the code to explain.
• Comment is a lie, it degrades over time and no one maintains it.
• Put effort into the code, not the comment.
• Don't check it TODO, once checked in, it becomes don't do [I disagree. Having TODO in code is quite useful. It is developer's responsibility to implement the TODO]
• Avoid mandated, journal, noise, position marker, closing brace, attribute (by author) comments.
• Avoid commented out code
• Don't comment code that happens in somewhere else. [I do not fully agree because sometimes we need to do that in oder to clearly explain the intention of the code. I would say avoid this if possible.]

Acceptable Comments

• Legal comment (copyright)
• Informative comment (design pattern convention naming that can't reflect the actual intention, complex regular expression)
• Amplification (emphasize the importance of why certain code is there)

Variable & Function Naming

• Should reveal it's intent
• The length of the variable name should be proportional to the size of the scope that contains it.
• Function is opposite, the larger the scope, the smaller the function is.

Code Reviews

• Time to spend in code reviews should same as amount of time to write the code
• Pairing in a good alternative than code reviews

Clean Code - Uncle Bob (Lesson 3)

Quality

• When you release code, you know it works.
• Ready to deploy (shippable) in each iteration (e.g. 2 weeks iteration)
• The code should be better over time
• Fearless competence - don't afraid to refactor or touch the code. When you touch the code, you break it, then the code is yours. So you avoid touching code. [This sounds so familiar! However, practically this is subjective. Sometimes you do want to minimize the risk with minimum code changes]
• Expect QA to find nothing.

Stable Productivity

• You do not get slower (feature production rate does not slow down) when the system gets bigger.

Inexpensive Adaptability

• Software must be changeable by design. That's why is it "Soft" ware.
• The cost of the change should be proportional to the scope of the change

Honest Estimate

• Always give estimate in a range from the best case to worst case scenario.

Clean Code - Uncle Bob (Lesson 4)

• No innovations have been made in the software programming for decades. All codes written are still sequence, selection and interaction.
• But hardware has gone crazy as compared to software.
• Senior software engineer need to say "NO" when the answer clearly is no. [This is subjective. In software, you do not have definite answer, so you shouldn't say no in my opinion. "NO" is also a negative word where people often think you're defensive. I will rephrase it with more convincing bullets]

Test-driven Development (TDD)

• TDD is discipline and is arbitrary.
• 3 TDD Rules
  1. You're not allowed to write any production code until you have first written a test that fails because the production code doesn't exist
  2. You're not allowed to write any more tests until all the tests are passed
  3. You can only write the minimum production code that makes the test compile or pass.
• TDD is like double entry bookkeeping in accounting (e.g. balance sheet)
• TDD is a significant skill. Learn it well first before you bring into the work.

Clean Code Uncle Bob (Lesson 5)

• Software architecture evolves, it is not fixed.
• The goal of software architecture is to minimize the human resource that required to build and maintain the system
• Writing clean code doesn't make you slow. You feel slow because of all these disciplines.
• Software has 2 values:
  1. Value of what it does
  2. Value of its structure (often get ignored)
• The second value is more important than the first one, because it makes the software flexible. Thus, the cost to change is minimized.
• Software engineer is responsible to communicate the second value to the stakeholders (who only cares about the requirement), and it is not an easy job.
• A good architecture allows major decisions to be deferred

Clean Code Uncle Bob (Lesson 6)

• Fundamental law of any projects you do. Pick any three...
  1. Good (Quality)
  2. Fast (Time to Market, Schedule)
  3. Cheap (Cost Effectiveness, Staff)
  4. Done (Scope)
• Manage the projects to the best possible outcome (maximize all four qualities above) based on data
• Agile is iterative development(for small team to do small things) and meant to provide the data (e.g. velocity and burn down charts)
• The deadline is fixed due to business reason but not the requirement which keep changing
• Requirements keep changing because the customer does not know what they want until they see it. Thus, the "Waterfall Model" is no longer applicable.
• Quality is the only way to go fast, do well, go fast. Assuming staff and schedule is fixed, we can only play around with the scope.
• Never put refactoring into schedule because we're constantly refactoring. Stakeholder doesn't care about it.
• [In my opinion, Agile is a good tool ONLY IF it is "properly" used by the project management. It is often being misused, for example, Garbage in, garbage out.]

Summary

These series of videos are motivating to watch, but a bit too long. I learned something from it but not significant. A lot of stuff is quite common sense, and it could be subjective to the company's culture.

Personally, I have never done test-driven Development (TDD) before and some minimum of pairing experience. If I have a chance, I would like to give TDD a try.

---

Originally published at https://vtsen.hashnode.dev.

Comments

[Talha Altınel]

"Comment is a lie, it degrades over time and no one maintains it." -code book seller bob

This guy is the best marketing person I have ever heard. Totally out of touch with today's doc gens and the importance of comments.

Learn it from here folks, don't do jabba for 25 years or you end up like this

[Vincent Tsen]

I used to write a lot of comments but I think if the code can explain itself, then you don't need to write comment. That is the ideal case.

However, in a complex software environement, comment usually cannot be avoided because when you look at the code, you have no idea. You rely on comments to tell you. Thus, comments become useful.

[Talha Altınel]

Exactly, I don't write comments for my personal projects but in bigger team projects, it is nearly needed and this also brings the necessary documentation policy for the business logic, not just code comments, it is 100% needed if you are building a library etc...

[Vincent Tsen]

Good one. I'm on the same page with you.

[bigbott]

If your code requires comments, it is probably requires refactoring in the first place. And/or appropriate architectural pattern. Possibly simpler one.

[Talha Altınel]

wrong, comment is for docs and drawing attention to avoid mistakes

google.github.io/styleguide/go/dec...

[Vincent Tsen]

Only if it is unavoidable. Assuming if you can code without comment, that can also avoid the mistakes, that will be ideal.

[Talha Altınel]

I agree on that, there is a balanceful ground, definitely we don't wanna read 180 lines of comments per 2 lines of code

[bigbott]

Thanks. Have been looking for such summary for years. Agree with Bob about comments.

[Jose Berengueres]

excellent recap! will use in my class!