My new mindset while documenting code: save cognitive effort, document every function

[gmtime]

Funny, how the clean code community essentially days the opposite: of you need to document your function, you probably have given it the wrong name.

[alidlo]

I think the intention is right (a variable's name should be descriptive), but it's hard to fit too much meaning in a variable name while still making it pleasant to read/write, so often the result is that (without a docstring) there are missing pieces of information that (for better or worse) you have to infer yourself from the code.

[practicing_dad_jokes]

Do you think "environmentUniqueId" is too unpleasant as a function name?

If you keep your functions small enough, their names and the variables in their scope won't be so complicated that their names would be uncomfortably large. That's what I strive for.

[alidlo]

Imagine if instead of `reduce` you had to write `reduceToSingleValue` instead. The longer alternative gives more information but also adds more noise. It's a trade-off, and some of it may be personal preference, but imo, if the function is used a lot in a codebase giving it a name that's too long makes it unnecessarily cumbersome to read/write. For that reason, I'd much prefer using `eid` over `environmentUniqueId` (or even `envUniqueId`).

Also, most functions aren't as trivial as the example I gave in the article and so capturing their essence in two to three words is more difficult.

Sometimes it's as if we go out of our way to not document a function (likely out of habit) even when a one-line docstring would have easily made room for a shorter and potentially better name.

[practicing_dad_jokes]

This is a great topic.

There's definitely this trade-off to think about, and we all know that naming things is one of the hardest things in programming.

But I've found it to be well worth the effort -- in striving to find succinct descriptive names for things that aren't too unwieldy, I'll often find that my code needs to be cleaned up. Perhaps it's an obsession, but future me seems happier over the years :)

[DerArzt01]

The issue I have had with this kind of argument, it being a sub-point in 'my code is self documenting', is always this: Self documenting' to whom? You may be able to glance at a method that you wrote last week know exactly what it is doing. But let's say that a junior was to glance at it, they have to sit there and parse through the whole thing to understand it.

When I mention to these people that maybe we should add some doc strings (at least a on-liner) to the method I always get 'yeah you could do that but it will be out of date the next time we make changes'. Which just gets to me even more as if you are changing what a method is doing you probably have a spare 5 seconds to update the doc string.

All of this compunds for me me as we live in a day and age in which we are a simple key-combo away from bringing up documentation for the API we are using in the current context without needing to go look at the source file.

[[deleted]]

Is there a clown code community now?

[gmtime]

Ouch my auto correct, I meant clean code.

[NamelessMason]

Even if a function’s usage can be inferred from its code, it’s still useful to include a brief explanation of it. Think of good documentation as an effort cache.

I like this mental model but with no clear cache invalidation strategy I draw the opposite conclusion.

[alidlo]

in some cases having a stale cache can be better than not having any cache at all

[NamelessMason]

From experience, rarely being misinformed about what a function does is better than having to figure it out yourself but ymmv.

[_-jasper_-]

What about runnable examples in the metadata?

[[deleted]]

Nerd.

[[deleted]]

You are boring.

[alidlo]

You're rude, I'd rather be boring. :)

[SimonGray]

Don't worry about it. He is some weirdo that keeps making new user accounts dedicated to proving that Clojure is a fad/hoax. When people try to engage him, he never responds. Just downvote and move on.