1.7 KiB
+++ title = "Things I Learnt The Hard Way - If A Function Description Includes An "And", It's Wrong" date = 2019-06-23
[taxonomies] tags = ["books", "things i learnt", "documentation", "single responsibility"] +++
Functions should do one thing and one thing only. I clear indication that you're breaking this principle is the need to add an "and" in its documentation.
This is kind like "sometimes rule", but most of the time, when you feel you need to add an "and" to the function documentation (its contract), then you're telling that that function is doing two (or more) things.
One of guiding principles of good code is the Single responsibility principle, in which each module/class/function should do one thing and one thing only. And, again, if you're saying that a function is doing "this" and "that", you can be sure it's not doing just one thing.
Ok, but what now? Well, you have two functions, with two distinct contracts. Ok, but you had those two being called, what happens now? Well, where you called one, you now will need to call two. If your preferred language have support for function composition, you can use that to group both functions again. This is the kind of stuff that you'll get when you learn to use functional programming.
{{ chapters(prev_chapter_link="/books/things-i-learnt/document-is-contract", prev_chapter_title="The Function Documentation Is Its Contract", next_chapter_link="/books/things-i-learnt/languages-docs", next_chapter_title="Good Languages Come With Integrated Documentation") }}