Julio Biason
5 years ago
3 changed files with 39 additions and 1 deletions
@ -0,0 +1,37 @@ |
|||||||
|
+++ |
||||||
|
title = "Things I Learnt The Hard Way - The Function Documentation Is Its Contract" |
||||||
|
date = 2019-06-21 |
||||||
|
|
||||||
|
[taxonomies] |
||||||
|
tags = ["en-au", "books", "things i learnt", "documentation", "contracts"] |
||||||
|
+++ |
||||||
|
|
||||||
|
When you start the code by [writing the |
||||||
|
documentation](/books/things-i-learnt/steps-as-comments), you're actually |
||||||
|
making a contract (probably with your future self): I'm saying this function |
||||||
|
does _this_ and _this_ is what it does. |
||||||
|
|
||||||
|
<!-- more --> |
||||||
|
|
||||||
|
Remember that the documentation must be a clear explanation of what your code |
||||||
|
_is_ doing; remember that good messages will make [reading the code only by |
||||||
|
the function documentation](/books/things-i-learnt/document-id) should be |
||||||
|
clear. |
||||||
|
|
||||||
|
A function called `mult`, documented as "Get the value and multiply by 2" but, |
||||||
|
when you look at the code, it does multiply by 2, but sends the result through |
||||||
|
the network or even just asks a remote service to multiply the incoming result |
||||||
|
by 2, is clearly breaking its contract. It's not just multiplying by 2, it's |
||||||
|
doing more than just that, or it's asking someone else to manipulate the |
||||||
|
value. |
||||||
|
|
||||||
|
Now, what happens when this kind of thing happens? |
||||||
|
|
||||||
|
The easy solution is to change the documentation. But do you know if people |
||||||
|
who called the function expecting it to be "multiply value by 2" will be happy |
||||||
|
for it to call an external service? There is a clear breach of "contract" -- |
||||||
|
whatever you initially said your function would do -- so the correct solution |
||||||
|
would be to add a new function with a proper contract -- and probably a better |
||||||
|
name. |
||||||
|
|
||||||
|
{{ chapters(prev_chapter_link="/books/things-i-learnt/document-it", prev_chapter_title="Documentation Is a Love Letter To Your Future Self") }} |
Loading…
Reference in new issue