TL;DR notes from articles I read today.
What is clean code?
Few key ideas from Robert C. Martin’s Clean Code:
- Even though perfect code is an illusion, understand that craftsmanship matters because high-quality (thoughtful, flexible, maintainable) code results in long-term payoffs for the business. Code that ‘just works’ may only offer short-term success.
- Put in the extra effort today to refactor and test your code, in order to save yourself (and others) pains tomorrow. Poorly crafted code unravels fast, while high-quality code saves money and builds customer loyalty while reducing technical debt.
- Take pride in your work but recognize that your code is not your own and must be used and understood easily by others. So, avoid clever hacks and sleights of hand no matter how much fun they seem while coding. Focus on code that’s simple in implementation, readable (with consistent naming conventions, spacing, structure, and flow), considerate of future consumers and professionals, tested, relentlessly factored and SOLID (following the principles for longevity, maintainability, and flexibility).
- Remember that the best way to write clean code is to do it all the time so that you retain and refresh the skill continually - even on your personal projects.
Full post here, 6 mins read
How to write good code documentation
- There is no such thing as self-documenting code but your code needs to be self-explanatory. Invest time to review your work and write clean, structured code. It is less likely to contain bugs and will save time in the long run.
- Ensure you practice continuous documentation within your development process so that it is appropriately prioritized and is written, reviewed and delivered on time with the code.
- You might write low-level tests for specific scenarios before the code, and leave architecture, user and support documentation to the end of the release cycle when all information is known and frozen. But store it all in one place and keep it up to date.
- Get feedback on your documentation too - both as a health check and for clarity and comprehensiveness - and incorporate it. One of the best ways to do this is Jason Freedman’s 30/90 feedback method. At 30% completion, ask a reviewer to look at the broad outline, flow, and structure of document. At 90% have them go over it with a fine-toothed comb. Have peer, user and expert sessions in between.
Full post here, 6 mins read
Embracing the chaos of chaos engineering
- You start with a hypothesis and you make an educated guess of what will happen in various scenarios, including deciding on your steady-state.
- Then you introduce real-world events to test your guesswork for hardware/VM failure, state inconsistency, running out of processing power or memory or time, dependency issues, rare conditions, traffic spikes, and service unavailability.
- After that comes doing test runs in production on the properly pretested codebase (though be cautious of doing this to safety-critical systems such as banking) and then complete your hypothesis based on how real-world events affect your steady-state.
- You should communicate your results not only to engineers but also to support staff and community managers who face the public.
- Use different tools to run your experiments and ensure you have alerts & reporting systems in place to minimize potential damage. Abort quickly if needed.
- Once you have defined ideal metrics and potential effects, increase the scope of testing by changing the parameters or events you test each time, applying fixes as you go till you find the points where the system really starts to break down.
Full post here, 6 mins read
Get these notes directly in your inbox every weekday by signing up for my newsletter, in.snippets().
Top comments (1)
I love your idea about the code is not a property of the programmer, the code is property of all people involved in the software lifecycle. Starting from clients, users, stakeholders, the company, our team members, future time programmers, operations, etc.
Great post!.