Comment

Comment by astrobe_

Beyond the satire, one is supposed to write code which is readable, and like often with written works, one has to think about the "audience", the readers. When you write technical documentation, you have to decide ahead of time the expected skill level of the reader - often that decision is written too in the intro as "prerequisite(s)".

When writing code you have the motto "don't make me think" in mind, but how to know what's the maximum level of trickiness for readers? There are familiar techniques and idioms when it is your main programming language, but they are not for someone using this language on the side.

In any case, neither code nor comments should be tutorials. To a reasonable extent, it is up to the reviewer to do their homework or just ask. Then based on that interaction you can add a comment or a parenthesis, or uncompress a bit the code. But not to the point that it means to "dumb down" things, because it is a downward spiral.

parent astrobe_ 1 year ago

Discussion

Live from the official Hacker News API

A modern reader for Hacker News · SvelteKit + Skeleton