After 13 years of development I know exactly what makes
software development a productive, efficient and happy activity.
And that is: keeping number of bugs, regressions and confusion
as low as possible, near zero to be precise.
I believe, I personally have achieved that. I used to spend about 80% of my time
on fixing bugs, being confused and depressed. Now, whenever I write code,
it works as intended almost immediately. I am also able to write big projects alone.
Of course, my big experience plays a large role, however there is something
that helps me probably even more than my experience. A methodology, which I
have spent a couple of years to think through. I am going to share it with you, and also
I want to share with you the VSCode extension that supports that methodology.
As a lot of people I used to code in JS and that was fine. Until I started
to work on bigger and bigger projects, and one day I reached the point
when I no longer wanted to fix all the bugs caused by the
weak type system. That was the time when I switched to TypeScript.
And I was incredibly happy with that. TypeScript kept preventing so many silly errors
that I was able to write even bigger projects. I thought that from that point
I could write projects of any size, because you know, whenever I forgot something
TypeScript would kindly remind me.
So I started to write my most complex project to time, alone. Everything
was cool, TypeScript kept reminding me about all the types I had.
But soon I started to feel some anxiety and headache. That feeling was familiar to me,
from the times when I tried to comprehend some spaghetti JS code.
But wait, that was my code, and it was written in a typed language, so why
did my head feel so badly? It's hard to believe, but it turned out that
in the middle of the project I started forgetting things like:
what was the project about, why was I writing it at all, what was its purpose,
and what did the code I had already written do on the high-level.
Those problems were shocking for me, but I had found a simple and intuitive solution
to them - documentation. A lot of it. And it helped. Until the time when
the documentation started to rot. That was a catastrophe. A documentation that
starts to rot does much more harm than no documentation at all. It confuses, it misleads and
it multiplies bugs.
I've wrote just a few paragraphs, but I am writing about quite long
and miserable periods of my life. I lost faith and confidence that I am able to write
something significant alone, even if I had all those years of experience.
In this depression I started to think what could be done. Is it even possible
to write documentation in such way that it won't rot?
The next few months I had come up with thousands of ideas, I was thinking them through,
filtering, testing them. In the end all of that has crystallyzed in HyperComments.
I haven't sleep tonight, because I wanted to finally fix the most critical bugs, so
this article may be a little raw, chaotic and shallow. That is also the reason why I am
going to only show one examples of usage, but you can follow the link (below) and see much more.
"The Plan" Technique
When you have a very complex task, that is tough to plan out entirely in your head, then
write it out as a plan:
/*
#Task 1#
#Task 2#
#Task 3#
...
*/
While writing this plan out, you will be naturally breaking down the task into smaller ones,
and you'll be getting a more and more detailed image of how the whole system should work.
When you finally have broken down the big task into smaller ones, and you are confident
that there is no or little obscurity left, you can start making the first task (Task 1).
Just start it with this comment:
@Task 1@
What's just happened is your plan is now connected with the code implementation.
Now, if you want to get the big picture, you may look at the plan, and whenever you want
to go down the details, you may search @Task 1@ with the help of your code editor.
If you're using VSCode, though, HyperComments
could help greatly: just click on a plan item and you'll be automatically navigated
to the implementation code. The extension does more than that! It will also
underline with red color those plan items which do not have corresponding implementation
tags (anchors). So that you won't forget to implement any of the steps!
Again, that's only one technique of many, I am going to continue writing on this subject, but I really need your feedback! Please support me by liking this article, trying the extension, filing bug reports, any of thus will be greatly appreciated.
I hope this will help someone!
Oldest comments (0)