Hey everyone,
It's been a while since I shared my last newsletter with you. To make it up and fight procrastination, I decided to hit the "publish" button today and share some good news and a short thought with you.
The Good News
✨I am excited to share that I am part of 40 people selected from different countries to participate in the three months mentoring program #RoadToGDE ☺️
On Documentation
As I was reading a nice article yesterday from a software engineering student, summing up some takeaways she has learned from her experience at a startup, some insights from Martin Fowler came to my mind.
"Document what you’re doing as you’re doing it. [..] I looked back at my code a couple of months later once requirements changed and the feature needed adjustment, and I couldn’t decipher a single line. Yes, documentation can be boring, but it is a very valued skill in personal projects and in industry."
Here is an answer from Martin Fowler that I’ve extracted from The Almighty Thud & CodeAsDocumentation:
- One of the common elements of agile methods is that they raise programming to a central role in software development. Part of this is classifying the code as a major, if not the primary documentation of a software system.
- Like any documentation, code can be clear or it can be gibberish.
- I think part of the reason that code is often so hard to read is because people aren't taking it seriously as documentation. If there's no will to make code clear, then there's little chance it will spring into clarity all by itself.
- It's a fallacy to conclude that declaring code to be documentation excludes other forms.
- Documentation must be brief. Only if it is brief will people read it and understand it. Only if it is brief will you bother to keep it up to date.
- A friend of mine told me about one project where they were reluctant to change class names, not because the code took too long to change, but the documentation took too long to change. When documentation becomes a problem you should deal with it. Throw at least half of it away.
What I’ve published recently?
During the past three months, I’ve managed to publish a few articles and videos:
Articles:
Videos:
Live Coding: Refactoring 2 Angular Components with the Container/Presenter Pattern (here is a written version)
Did you know?
You can support me and other writers by signing up for Medium here.
You can join 6K+ students and benefit from my Udemy video course: How to Identify, Diagnose, and Fix Memory Leaks in Web Apps
Till next time, have a nice day!
— Rakia