The source content for blog.juliobiason.me
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.

34 lines
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 = ["en-au", "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.
<!-- more -->
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](/books/things-i-learnt/document-is-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](https://en.wikipedia.org/wiki/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](/books/things-i-learnt/functional-programming).
5 years ago
{{ 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") }}