So the title of this article is a play on "whatever driven development. I'm not really advocating for a new or different style of programming.
I am encouraging you to start documenting before you even start coding.
I'll be honest. It took me forever to actually start documenting my code. I've always been a supporter that code should be "self-documenting". But, in reality, this was just a pure lazy stance on my part.
No matter how well written my code was, I could not for the life of me read it again after 6 months.
Why did I write that logic that way?
If I couldn't read it in 6 months, how could I expect other engineers to understand my interesting attempts at programming?
I'll tell you -- By being pure evil.
It can't happen. It doesn't happen.
If you want to know the easiest way to make sure that functionality gets duplicated in a system.. Don't document your code.
Other engineers will surely just ignore your code and write it again differently.
But I'm not here today to harp on why you are evil by not documenting your code. There are plenty of other articles on the Internet that can do plenty good making you feel bad.
I am more interested in sharing something really neat I discovered when I started to get serious about documenting my code.
It made writing my code faster and easier.
Writing logic in a human language before you write the code functionality makes your code better.
1. It fills in the gaps.
Let's be honest. We start writing a function and don't really understand how it is going to get to the desired result. We know that we want to return a string that has been modified by some api. But we don't really know how we are going to the end result. We just know that we will.
What if you documented the steps first?
Brilliant.
What if you wrote down in a human language the steps required to fulfill this functionality need. In order to fulfill this function, you need to do X, Y, Z.
Write it down. Then just program it.
/**
* toSlug takes a string and returns a url friendly slug.
* 1. lowercase the string.
* 2. Replace all non-alphanumeric characters with hyphens.
* 3. Trim white space.
* 4. Remove duplicate hyphens.
*/
toSlug(str: string): string {
..
2. It prevents useless code.
Sometimes, we write code that really doesn't belong. We think it does and we think it solves problem A. But by the time we finish, it isn't adding any value and we forget to remove it.
Unused code is terrible code.
Writing documentation before writing code prevents unused code because it gives you a chance to think through the logic. You can write out the reason "why" you need the function in a human readable sentence before programming it.
And many times, you come to the conclusion that there is another (better) way to solve the problem that already exists.
3. It prevents bugs.
Ever have a stupid bug that was difficult to dissect? It's likely because the logic wasn't really documented well. Those facepalm moments take hours or days to uncover but are really simple fixes.
Best way to solve them?
Document first.
When you write out your logic. You can check and recheck it fairly easily. You write out your logic to return back a variable on an object but then realize what if the variable is null? Add some documentation and good to go.
// We need to check that the user exists before returning data.
if (!user) {
return {};
}
4. It Makes Tests More Complete.
Unit tests are the holy grail but nobody knows what to test. Sure, create a test that makes sure if you pass in a string that it returns back a concatenated string. But that is the bare minimum.
Which constitutes 90% of all tests. It checks that the response returns back the right type and result for a single request. It doesn't offer up limits or provide multiple options.
Tests are generally written to succeed with best case scenario. We are told tests should be written to fail but rarely is that true. Most of the time, tests are written to pass.
This isn't the case if you document first!
When you document first, you have plenty of testing scenarios and opportunities. You know your limits. You know what can fail. You know what to check.
In other words, good documentation can actually make those silly tests useful.
Documentation Driven Development is the Secret to Good Programming.
We always think of documentation for the stranger programmer in the future that may or may not exist. It is always about the future state.
But this is far from the truth.
When you start with documentation, your code is better and you level up as a software engineer.
There's an old adage that says "What separates a hobbyist programmer from a professional engineer? Documentation."
It is true.
Top comments (0)