You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
29 lines
1.1 KiB
29 lines
1.1 KiB
5 years ago
|
+++
|
||
|
title = "Things I Learnt The Hard Way - Documentation Is a Love Letter To Your Future Self"
|
||
|
date = 2019-06-21
|
||
|
|
||
|
[taxonomies]
|
||
|
tags = ["en-au", "books", "things i learnt", "documentation"]
|
||
|
+++
|
||
|
|
||
|
We all know writing the damn docs for functions and classes and modules is a
|
||
|
pain in the backside. But realizing what you were thinking when you wrote the
|
||
|
function will save your butt in the future.
|
||
|
|
||
|
<!-- more -->
|
||
|
|
||
|
When I say that it will save your butt, I don't mean the documentation will
|
||
|
tell you something like "Here are the lotto numbers in 2027"[^1] or "If John
|
||
|
complains about your future code review, here is some shit he did in the
|
||
|
past".
|
||
|
|
||
|
I mean, it will explain how the _flow_ of your code is expected to do. Imaging
|
||
|
this: pick your code and replace every function call to its documentation. Can
|
||
|
you understand what it is expected by reading that? If you can,
|
||
|
congratulations, you won't have a problem in the future; if you can't... well,
|
||
|
I have some bad news for you...
|
||
|
|
||
|
[^1]: Please, don't make me revise this in 2027... :(
|
||
|
|
||
|
{{ chapters(prev_chapter_link="/books/things-i-learnt/future-trashing", prev_chapter_title="Future Thinking is Future Trashing") }}
|