Clean Code

Software project requirements are often not fully known in advance, requiring teams to learn a significant portion of the necessary information during the development process. This frequently leads to the addition of new features after the initial requirements and design phases, as well as extensive debugging. A key property of software is its ability to improve a system without changing the hardware. To take advantage of this flexibility, software must be designed in such way that it is easily modifiable. Otherwise, it risks becoming as inflexible as hardware. Since most of the development time is spent reading and modifying code, it is imperative to optimize for this fact which means writing clean code, i.e. code that is easy to understand.

Image reference: When Understanding means Rewriting

Clean Code - Uncle Bob / Lesson 1:

• [28:51] It is not the old people training the new people it is the old code training the new people.
• [31:06] No one writes clean code first because it is just too hard to get the code to work... Cleaning code requires as much time as making it work in the first place. Nobody wants to put that extra effort in. You are not done when it works, you are done when it's right/clean.
• Clean code should read like well written prose.
• [46:30] Every line in a function must be at the same abstraction level.
• [58:45] A function should do one thing, i.e. you should not be able to extract another function from it.
• Don't pass a boolean to a function. Bad: setCentered(true, false). OK: setVisible(true). Using enumeration variables or constants rather than a boolean variable, you make your code more readable, e.g.repaint (PAINT :: immediate).
• Replace switch/if with polymorphism
• Command and query separation: A function returning void must have a side effect [change system state], a function returning a value should have no side effect. With this convention, when you see a function that returns a value, you assume it is safe to call it because it should leave the system in the same state before you called it.

Lesson 3:

• [31:27] The design and code should get better with time, not get worse [continuous improvement].
• [32:15] If you touch it [the messy code], you will break it. If you break it, it becomes yours(!) Minimize personel risk vs improving a messy system.
• Unit tests results in fearless competence.
• [35:32] Always check it in a little bit better than you found it.

Tools are not the Answer: Raise the level of software discipline and professionalism. Never make excuses for sloppy work.

When working in an environment where messy code is common, it's crucial to commit to the repository in as small increments as possible. This is because even minor code changes can unexpectedly break the system. Often, you may only realize this after several days or weeks. Given the complexity of the code, your primary method of diagnosing the issue will be reverting to earlier revisions. If your commits are small, it will be much easier and quicker to isolate the cause of the code breakage.

TortoiseSVN: List all externals in a repository

When you have a repository that uses other repos as externals, the easiest way is to right click on your local repo root folder and select Branch/tag. The window will display at the bottom all externals in that repo.

When you tag a repo, don't forget to check all externals so that when at a later date you go back to that tag, the externals will also be in their revision of the tag date. If you do not check, they will come back as head revisions wich might cause problems if your tagged non-external code is not consistent with the latest revision of external repos. The only problem with this scenario is that if you test your code and then let time pass before tagging, another developer might update one of the externals and when you tag, TortoiseSVN uses the revision on the server, not your local.

If you want to be sure that you tag the external revision in your local, you should use svn copy [local path] [server path] --pin-externals -m "this is a test"

Note that you need version 1.9 or later of TortoiseSVN in order to use pin-externals.