People say, "Only when there is Hakuraku¹ in the world can there be chollima²," which suggests that "chollima" is Hakuraku's invention. If horses had consciousness, they would probably despise the concept of chollima. The fortunate horses gallop freely in the wilderness, expressing their true nature; the unfortunate ones, though confined to stables, at least preserve their lives. However, the "chollima" favored by Hakuraku must follow generals on campaigns, facing constant dangers and extraordinary hardships. When they finally die, if their rider has some conscience and plans a grand burial, he might even be dissuaded:
"The sage Confucius did not concern himself with horses. If you, my lord, lavishly bury a horse, it will dishearten the people³ who follow you. Better to cut it into small pieces and distribute the meat to everyone—let the iron pot serve as the coffin and stomachs as graves.
This is the proper funeral for a horse."

Therefore, "Hakuraku is not always present" is truly a stroke of luck. If Hakuraku were always around, who knows how many more "chollima" would die unnatural deaths? Just as the Literary Chinese idiom "懷才不遇" (having talent but not having an opportunity) also describes a stroke of luck. Wealth comes after talents, as in Literary Chinese the kanji "才" (talent) can be used as the kanji "財" (wealth), so the Literary Chinese idiom "懷才不遇" (having talent but not having an opportunity) can be interpreted as "懷財不遇(盜)" (having wealth but not having an opportunity to be robbed). If someone carries a fortune and walks alone in the dark of night without meeting robbers or thieves, that is indeed fortunate.

If one is incompetent, they are even more lucky. If a horse is incompetent, even when Hakuraku approaches, it need not fear. It's like a poor person walking at night—those who would rob for wealth have nothing to target.⁴

In the 7th volume of Planting Seeds in Forests and Cultivating Virgin Soil in Mountains,⁵ there is a story about "following the map to find a horse":

Hakuraku's Manual of Horse Evaluation contains the phrase "a high forehead, a pair of big and round eyes,⁶ big and regular hooves." His son went to search for horses based on the Manual. When he saw a large toad, he told his father: "I found a horse that closely matches the description, except the hooves are a bit irregular." Knowing his son's foolishness, Hakuraku turned his anger into laughter and said: "This horse is too good at jumping to ride on."

Hakuraku's son, following his father's Manual, found a toad. I prefer to believe this was his way of expressing to Hakuraku that he refused to evaluate horses. Having spent his life evaluating horses, Hakuraku's son probably grew up in the company of horses. As a child, he might not have understood what "thousand-li ability" meant. What the child saw were one adorable horse after another, one horse after another that was kept for a while and then sent away, and one horse after another that perished on battlefields and buried in human bellies. Naturally, he could not approve of what Hakuraku has done and certainly did not wish to evaluate horses himself. So he found a toad instead. This was Hakuraku's son's foolishness. Hakuraku had once recommended another famous horse tamer Nonapath⁷ to Duke of Cin ⁸, showing that he was also skilled at evaluating people, so he understood his son's intention. That's why he "turned his anger into laughter." First came anger, then helpless, bitter laughter. "This horse is too good to ride on" was his metaphor showing that he understood his son's meaning—horses are by nature unruly and out of human control.

English translation by GPT-4.1 and proofread by Gemini 2.5 Pro and weakish.

按圖索驥

人道「世有伯樂，然後有千里馬」，可見「千里馬」是伯樂的發明。 「千里」云云，馬若有知，恐不以爲然。 馬之幸者，馳騁於曠野，盡其天性；不幸者，雖處槽櫪之間，猶得全生。 然而被伯樂相中的「千里馬」，卻是隨將帥四處出征，危機四伏，艱險異常。 最後死了，主人有點良心，打算厚葬，說不定還會遭到謀士的勸阻：

「孔聖人不問馬，主公您厚葬馬，會讓跟隨您的士人寒心呀。 不如割成小塊，分給大家吃了，鐵鍋作棺槨，腸胃爲墓地，這纔是馬該有的葬禮呀。」

所以「伯樂不常有」，實在是幸事。 倘若伯樂常有，不知又會有多少「千里馬」死於非命。
就像「懷才不遇」也是幸事。 「才」通「財」，「懷才不遇」，便是「懷財不遇盜」。 若是一人攜帶巨款暗夜獨行，沒碰上強盜小偷，那實在是幸事。

若是無能，那就更幸運。馬若無能，伯樂走到跟前，也不懼。 好比窮醜之婦夜行，劫財劫色者皆無從下手。

明楊慎《藝林伐山》卷七裏有一個「按圖索驥」的故事：

伯樂《相馬經》有「隆顙蛈日，蹄如累麴」之語，其子執《馬經》以求馬， 出見大蟾蜍，謂其父曰：「得一馬，略與相同；但蹄不如累麴爾。」 伯樂知其子之愚，但轉怒為笑曰：「此馬好跳，不堪御也。」

伯樂的兒子根據老爸的《馬經》，找到了一枚癩蛤蟆。 我願意相信，這其實是在向伯樂表態自己不相馬。 伯樂一生相馬，伯樂之子小時候大抵是與馬爲伴，千里之能什麼的，小孩未必明白。 小孩眼裏看到的，是一匹又一匹可愛的馬兒，是一匹又一匹養了一段時間就被送走的馬兒，是一匹又一匹喪生沙場、葬於人腹的馬兒。

因此自然無法認同伯樂的行爲，自己當然更不願相馬。所以便找了一個癩蛤蟆。 這是伯樂之子的愚處。伯樂曾經推薦九方皋給秦穆公，可見他也善相人，自然明白了其子的意圖， 所以說是「伯樂知其子之愚，但轉怒為笑」。起初是怒，後來是無奈苦笑。 「此馬好跳，不堪御也。」便是表明自己心知其子之意，癩蛤蟆是個隱喻——馬性跳脫，不堪爲人所御。

HTML is a Text Markup Language

HTML stands for HyperText Markup Language. As the name suggests, HTML is used to mark up text, not to describe user interfaces. Although it has been extended over time, it still doesn't excel at expressing user interfaces due to compatibility with its original design.

Of course, JavaScript was originally intended to decorate pages, for creating some sparkly little widgets. But regardless, JavaScript is still a general-purpose programming language, and JavaScript updates at a much faster pace than HTML. So when choosing between two evils, we'd rather write JavaScript than HTML.

In fact, frameworks that use pure HTML are not common. Because HTML is too unwieldy, frameworks that use HTML usually need to add some extras, such as *ng (Angular) and v- (Vue) attributes, or JSX (React). Otherwise, they create a template language similar to HTML.

Actually, this patching approach is not as straightforward as directly writing JavaScript.

The Kotlin and Ceylon Approach

Some newer languages directly use native structures to express HTML.

For example, in Kotlin, HTML is written like this:

fun result(args: Array<String>) =
    html {
        head {
            title {+"XML encoding with Kotlin"}
        }
        body {
            h1 {+"XML encoding with Kotlin"}
            a(href = "http://kotlinlang.org") {+"Kotlin"}
            p {
                for (arg in args)
                    +arg
            }
        }
    }

This is not some template language. This is Kotlin, native Kotlin.

Kotlin provides this syntactic sugar:

f({ "an anonymous function" })

can be written as

f { "an anonymous function" }

So html { ... } is a Kotlin function call, and the other HTML elements inside {} work the same way.

The html function is defined roughly like this:

fun html(init: HTML.() -> Unit): HTML {
    val html = HTML()
    html.init()
    return html
}

Essentially, it initializes an HTML instance.

The corresponding HTML class definition:

class HTML : TagWithText("html") {
    fun head(init: Head.() -> Unit) = initTag(Head(), init)
    fun body(init: Body.() -> Unit) = initTag(Body(), init)
}

Using native Kotlin language to express HTML means we can use all of Kotlin's native language features, and no longer need to worry about the limited expressiveness or strange syntax of HTML template languages. At the same time, this naturally ensures type safety for HTML templates.

Similarly, in Ceylon, HTML is written like this:

Html {
    doctype = html5;
    Head {
        title = "Ceylon: home page";
    };
    Body {
        H1 { "Hello `` req.queryParameter("name") else "World" `` !" }
    };
}

This uses Ceylon's syntactic sugar for named parameters, equivalent to:

Html(doctype = html5, Head(...), Body(...))

Html is a class provided by the standard library, Html { ... } is initialization, (Ceylon directly constructs class instances through C(), no need for new) This is also native Ceylon. The approach is similar to Kotlin's.

The design of Python is well considered. Also, the community tends to adhere PEP 8.

Python dose have some flaws, but most of them are fixed by type hints. For example, Python does not have the capability to define a constant variable, but PEP 591 introduces Final.

Personally I put a semicolon at the end of a mutation, e.g. a.append(1). This is inspired by the distinguished coding style used by "A Little Java, A Few Patterns".

Pie p = new Crust();
Pie p = new Top(new Anchovy(), p)
; // the future begins, i.e. from this line on, references to `p` reflect the change

However, this does not work with popular auto formatting tools such as black. Therefore, I do not adhere to this rule in some projects.

Use when expressions for cases, avoid other usage of when

Avoid use when statement, which is not exhausted. Just use if ... else if ....

Kotlin uses when for both case and cond, which is confusing. Thus avoid use when expression for cond.

Avoid variadic functions

Kotlin uses Array<T> for vararg p: T underhood but special array types for basic types, e.g. IntArray for vararg p: Int.

However, p: Array<T> and vararg p: T behaves differently. In other words, given a function Array<T> -> Unit, we do not know how to invoke it just from its signature.

Array<T> -> Unit may be an infix function, but all infix functions can be invoked as normal functions.

Avoid object.invoke

Without define invoke method for objects, every time I see CapsName(something), I am sure it will return an instance of CapsName, nothing else.

If we use lower case for object name, then once we see lowerCase(something), we may think it is a function. But we can pass neither lowerCase nor ::lowerCase to a higher-order function.

Avoid return in lambda.

Control flow return in lambda returns the outer function. This is confusing.

Reduce using component object

Kotlin supports top level functions, often cleaner than component objects.

Reduce using normal function

They are not first-class:

• They have to be referred as ::f.
• And invoking them requires intermediate variable (::f() won't walk).
• Only Foo::bar is referable. foo:bar is not supported.

Use val f = fun()... except for:

• main
• inline for reified generics
• tailrec

Annotate @Throws

• for documentation
• for calling in try catch clause from Java

Overload operators consistently

Overloading an operator should be consistent to all types supporting the operator.

Reduce using infix functions

Infix functions provide a new syntax for function calls, similar to operators.

Only use infix functions when they are obviously cleaner than non infix form.

The goal of coding style is readability

If there is a good reason to go against the style, just do it.

Avoid regression

So we don't fix bugs by introducing new problems. That way lies madness, and nobody ever knows if you actually make any real progress at all. Is it two steps forwards, one step back, or one step forward and two steps back?

-- Linus Torvalds

Prefer small functions

• Extract small functions from a complex function.
• One function should only do one thing.

Avoid top level variables

• Prefer passing parameter to function.
• Local variable is fine.
• Top level immutable value is fine.

More documentation comments but less inline comments

Programming languages are clearer than natural languages. So in most cases try to express as much as possible in programming language itself. Also, a compiler cannot warn you that comments is outdated. And an outdated comment can be very misleading.

• Use meaningful function and variable/value name.
• Declare local variable near its usage.
• Avoid deep nested function call expression. Extract meaningful immediate value declaration.

Here 'commenting' mainly refers to inline comments, i.e. comments explaining implementation details. Doc annotation of public modules and functions on their usage is fine.

Break long line of parameters logically

A simple approach is break for one, break for all. To save lines, related parameters may be grouped in one line.

Prefer readability to testability

The main audience of code is human beings, not tests.

Improving testability should not harm readability.

Obscuring code to improve testability may bring in potential bugs not caught by tests.

Prefer snake_case to camelCase

camelCaseAreHardToReadIfThereAreMoreThanThreeWords

snake_case_is_much_easier_to_read

Exceptions:

• TypeName since TypeNamesWithMoreThanThreeWords should be avoided.
• FooBar fooBar so wherever we see fooBar, we know it is of type FooBar.
• Keep a balance between preference on snake case and consistency with existing code in the project and/or the community.

Prefer explicit else branch

Some languages make the else clause of if mandated. This is a good design.

For other languages, prefer explicit else branch over fall through control flow.

For example:

Boolean if_else(Integer x) {
    if (x > 0) {
        if (x < 10) {
            return false;
        }
    } else if (x < -10) {
        return false;
    }
    return true;
}

It is short, but difficult to figure out the control flow.

Rewrite it more explicitly, without omitting else branch:

Boolean if_else(Integer x) {
    if (x > 0) {
        // This is for demonstration only.
        // `if (x > 0, x < 10)` is clearer.
        // Pretend there were more complex branching here.
        if (x < 10) {
            return false;
        } else {
            return true;
        }
    } else if (x < -10) {
        return false;
    } else {
        return true;
    }
}

Also, avoid using variable to save else branch.

For example:

variable Integer x = 0;
if (condition) {
    x = 1
    ;
}

can be rewritten to

Integer x;
if (condition) {
    x = 1;
} else {
    x = 0;
}

Only use i++ to increase i

y=i++ and y=++i is really confusing to me.

If the language allows ++ operators, only use i++ to increase i, i.e. just the statement i++;. I think a meaningful evaluated value of i++ should be void if a programming language allows ++.

The same applies to i-- and --i.

Do not use return value of assignment statement

Similarly to usage of i++, if assignment statements of the language return value, do not use them.

Test against true/false

Condition tests should accept a boolean value. So we do not need to remember rules for truthy and falsy values. For example, in Ruby only false and nil are false, but in Python, '', 0, (), [], and {} are also false.

Prefer

if not a.nil?
  # do something
end

over

if a
  # do something
end

Prefer explicit type annotation

Some languages allow you to use auto, var, etc. to let the compiler infer the variable type for you. Use this feature sparingly. Explicit type annotation serves as documentation. Omitting them may reduce readability of code.

Exceptions:

Prefer

value variable_name = ClassInterface<TypeParameter>();
value variable_name = ClassInterface()

to

ClassInterface<TypeParameter> variable_name = ClassInterface<TypeParameter>();
ClassInterface variable_name = ClassInterface();

Think long and hard when you want to omit type annotation under other conditions.

Also, for languages where variable declarations and assignments are indistinguishable in syntax, e.g. Python, type annotation helps to distinguish them.

Use semicolons to remark mutation

"A Little Java, A Few Patterns" uses a special coding style to remark mutation:

class PutSemicolonOnItsOwnLineForMutability
{
    Pie p = new Crust();
    Pie p = new Top(new Anchovy(), p)
    ; // the future begins, i.e. from this line on, references to `p` reflect the change
    Pie yy = new Bottom();
    yy.addTop(new Anchovy())
    ; // same as above
}

This is a brilliant idea. In languages semicolons are not mandatory, a semicolon can be used at the end of the line to remark mutability.

Formatting style does not affect AST and thus is unlikely to affect readability of code. If they do, it can be automatically adjusted via tools.

Use the official formatter if the language tool chain includes it, for example:

• go fmt for Go
• deno fmt for Deno
• rustfmt for Rust

Since different contributors may have different formatting preferences configured in their editor/IDE, with different rules or formatters, formatting should be configured at the project level, enforced by commit hook automatically. This is the best practice.

If formatting is not configured at the project level, it is a good idea to only commit in non-whitespace changes, to avoid formatting changes pollute repository history. For example, with Git:

git diff -w > changes
# review changes, run tests, etc.
git reset --hard
patch < changes
# stage and commit

If the project does not configure auto formatting, and you need to review someone else's commits with a lot of formatting changes, you can use git diff -w to ignore whitespace, or use similar options in other tools, such as "Hide whitespace changes" in GitHub's "Diff settings".

Eclipse archived the Ceylon project.

(Ceylon) failed its transition to Eclipse and the community gave up.

-- Eclipse Ceylon Termination Review

Avoid ... then ... else ...

I feel A then B else C confusing.

Readers may think A then B else C means A ? B : C in other languages, but they are not the same:

1. A then B else C is actually (A then B) else C:

   • A then B evaluates to B if A is not null, otherwise evaluates to null.
   • X else Y evaluates to X if X is not null, otherwise evaluates to Y.

2. Thus the type of B is T given T satisfies Object, i.e. requires to not be null.

Avoid foo { "bar"; }

In Ceylon, foo { "bar"; } and foo { "bar" } are semantically different, which may be confusing.

Either write foo("bar") or foo { parameter = "bar"; }, never write foo { "bar"; }.

Occasionally, foo {"bar"} may be used. But foo({"bar"}) is often preferred.

Prefer switch case over if else.

Cases in switch need to be both disjoint and exhausted. Using a strict form helps to reduce chances to miss corner cases.

For example, suppose we have the following code:

Path path = current;
if (is Directory path) { // typo, should be `path.resource`.
    // ...
} else { // dead code
    // ...
}

There is a typo in the above code, path should be path.resource. So the above code will never go into the else branch, since a Path is always not a Directory.

However, if we use switch with explicit cases:

switch (path)
case (is Directory) {
    // ...
}
case (is File|Link|Nil) {
    // ...
}

The compiler will refuse to compile, saying cases are not exhausted.

switch can also be used as a workaround of Ceylon's assignment returnning assigned value:

variable Boolean b = false;
if (b = true) {
    print("typo in the above line: `=` should be `==`");
} else {
    print("Use switch to avoid this mistake.");
}

switch (b)
case (true) {
    print("Avoid typo of `==`.");
}
case (false) {
    print("assignment should not return a value in Ceylon.");
}

Pay attention to compiler warnings

If necessary, use annotation to suppress false positive warnings.

For example:

"The ultimate exception handler."
suppressWarnings("expressionTypeNothing")
shared void run() {
    try {
        main();
    } catch (UsageError e) {
        process.writeErrorLine(e.message);
        process.exit(e.exit_code);
    }
}

Failures

Use exceptions for failures that are unrecoverable by immediate calling code, like bugs in program logic, network failure, and so on. So they can be handled by some centric infrastructure code.

Use return values (union types) for recoverable failures.

Be careful with side-effect functions. They are not type safe as side-effect functions with checked exceptions in Java. The ceylon compiler does not force you to check function's return value when invoking functions as side-effects. For example, when getting return value from result = f(); where f is Result?(), Ceylon does force you to check whether result is null or not. However, invoking f as side-effects f(); will silently ignore its return value, without checking for failures.

Be careful when indexing slice

Index out of bounds are not checked at compile time for slices (including strings, a.k.a. slices of bytes).

You may consider using the indexing functions from the gosugar package instead, which will automatically check slice length for you.

Functions, interfaces, pointers may be nil

The compiler does not check nullability for functions, interfaces, and pointers.

Thus, any function taking a function, an interface, or a pointer, needs to check whether input is nil itself. Since all methods implicitly accept a pointer, all methods should check whether their receiver is nil or not. Though, if you are careful enough, you may omit checking nullability in unexported functions.

You can use the RequireNonNull function from the goaround package to check every non-nullable parameter, which will panic if the parameter passed in is nil.

Explicitly check type implementing interface at compile time

Use the var _ Interface = (*Type)(nil) trick.

Stay clear. Stay explicit.

• Use naked return sparingly, e.g. in very short functions with single exit point. Alternatively, always use explicit return.
• Do not omit top level type names in map literals.

Only use head statement in if to declare variables

Like for, the if statement can start with a short statement to execute before the condition. This often harms readability thus it should only be used to declare variables to limit their scope.

The same applies to switch.

Only use switch for cases

In Go, switch can be used for both case and cond. To avoid confusion, I always use switch for case. I use if ... else if instead of switch for cond.

Only use defer for cleanups

Use defer carefully.

Do not rely on zero values

Do not rely on Go's default initialized value. Initialize it explicitly instead if the value is intended to be used later.

Similarly, always check presence when retrieving elements from a map.

Similarly, always check presentence when retrieving elements from a map. For example, if you want to retrieve an integer from a map, and use 0 if the key is missing:

element := m["id"]

The above code utilizes the zero value of missing keys. This makes the code shorter, but less clear (The value is absent? The value happens to be zero?)

Verbose and explicit code is preferred:

element, present := m["id"]
if present {
    return element
} else {
    return 0
}

Since Go will always initialize zero value on declaration, the compiler will not complain declaration without initialization. Thus, we should initialize variable on declaration whenever possible.

For example:

var s string
if x < 0 {
    s = "0"
} else {
    s = "1"
}

We can extract it as a function:

func f(x int) string {
    if x < 0 {
        return "0"
    } else {
        return "1"
    }
}

var s string = f(5)

The compiler will check the function returns on all branches.

Do not use %#q in printf

There are more good things to remember than the special rules of %#q.

Include files

Simple rule: include files should never include include files. If instead they state (in comments or implicitly) what files they need to have included first, the problem of deciding which files to include is pushed to the user (programmer) but in a way that's easy to handle and that, by construction, avoids multiple inclusions.

There's a little dance involving #ifdef's that can prevent a file being read twice, but it's usually done wrong in practice - the #ifdef's are in the file itself, not the file that includes it. The result is often thousands of needless lines of code passing through the lexical analyzer, which is (in good compilers) the most expensive phase.

-- Rob Pike Notes on Programming in C

The real problem is C does not have a proper package or module system. Leaving the user to manually composite include file list is a workaround.

Reduce macros

As a general rule, #ifdef use should be confined to header files whenever possible. Conditionally-compiled code can be confined to functions which, if the code is not to be present, simply become empty. The compiler will then quietly optimize out the call to the empty function.

C preprocessor macros present a number of hazards, including possible multiple evaluation of expressions with side effects and no type safety. If you are tempted to define a macro, consider creating an inline function instead. The code which results will be the same, but inline functions are easier to read, do not evaluate their arguments multiple times, and allow the compiler to perform type checking on the arguments and return value.

-- Linux kernel coding style

Reduce inline functions

Since their code is replicated at each call site, they end up bloating the size of the compiled kernel. That, in turn, creates pressure on the processor's memory caches, which can slow execution dramatically.

More recent compilers take an increasingly active role in deciding whether a given function should actually be inlined or not.

-- Linux kernel coding style

Prototypes should have parameter names

Prototypes do not require parameter names. But writing them out helps to understand the usage of functions.

Do omit parameter names when it is obvious, for example,

int plus(int, int);

is preferred to

int plus(int adder, int addee);

Comment FALLTHROUGH in cases

Non default cases in switch statements should end with either break or FALLTHROUGH comment.

Mark non-return

Mark a function never returns (always abort) with __dead.

To be compatible with different operating systems, use a shim:

/*
 * Public domain
 * sys/cdefs.h compatibility shim
 */

#include_next <sys/cdefs.h>

#if !defined(HAVE_ATTRIBUTE__DEAD) && !defined(__dead)
#define __dead          __attribute__((__noreturn__))
#endif

This is based on the code at openntpd, with #ifndef and __pure removed.

Standards

• Lua still sticks to ANSI C (C89, gcc -ansi). But for most programs, I think, a more recent version is more convinient. For example, C17 without extension, -std=c17 -pedantic.
• Use POSIX.1-2008/POSIX.1-2017, #define _XOPEN_SOURCE 700.

Gemini is a protocol "in between Gopher and the web"*, but for me, Gopher is more like FTP, and Gemini is more like HTTP. Gemini does have some pitfalls in its design+, but it is still a good enough alternative to Web with an active community.#

Gemini Text

If Gemini is to HTTP, then Gemini text is to HTML. It's a line-oriented minimalistic hypertext markup language inspired by Markdown and gophermaps. It has link lines and preformatted text lines. Optionally, it supports three levels of headings, unsorted lists, and quote lines.

There is no syntax for escaping special markers. In other words, it assumes no normal text line will starts with =>, ```, *, #, or >. And no lines in preformatted text block will start with ```.

A Bit of History

Setext (Structure Enhanced Text) aims to be easily readable without any parsing or special software. This inspires both ReStrucuterdText and Markdown.

The idea of Markdown is

to make writing simple web pages, and especially weblog entries, as easy as writing an email

-- Aaron Swartz

At that time, ReStrucuterdText seems too complex:

Is there a Perl implementation of reST, or a Movable Type single-file plug-in wrapper? As far as I’m aware, no. So, even without any arguments about reST’s syntax, I just don’t see how one could argue that I could have just used reST.

And if I was going to write my own code, there was no way I was going to write code to re-implement reST’s rather large feature set. I’m much too lazy.

-- John Gruber

What Gruber and Swartz could have done was to implement a subset of ReStrucuterdText. But they decided to "develop the perfect format".

Partly due to its simplicity, Markdown became popular. Then, people want more and add more. Today Markdown turns out to be as complex, if not more complex than, ReStrucuterdText. And unlike ReStrucuterdText, Markdown is inconsistent among applications and platforms.

Maybe I should not get surprised. After all, HTML was extremely simple at the time of Setext.

Common Markup Among Setext, ReStrucuterdText, and Markdown

To me, the best parts of reST are the parts it borrowed from Setext.

-- John Gruber

However, there are few common markup among Setext, ReStrucuterdText, and Markdown.

Heading
=======

Sub-heading
-----------

**bold**

* bullet list
* another item

And the bullet list markup seems to be the most pervasive one. It is the only common markup among Setext, ReStrucuterdText, Markdown, Usemod wiki, and godoc comment.

Compared to Svelte Reactive Blocks, Preact Signal feels more verbose but less surprising to me.

Svelte advertises itself as bringing reactivity to JavaScript itself:

<script>
	let x = 0
	let y = 0
	$: total = x + y
</script>

<div>
<p>{x} + {y} = {total}</p>
<button on:click={() => x++}>Increase X</button><br />
<button on:click={() => y++}>Increase Y</button>
</div>

Brief. Short. And except for $:, every token is intuitive.

In the above code, $: means total depends on the value of x and y. Thus, when either button is pressed, the {total} part will be rerendered automatically.

However, in the following code sample, total will only get updated when x changes, not when y changes!

function yPlusAValue(value) {
  return value + y;
}

$: total = yPlusAValue(x);

This surprising behavior is because the Svelte compiler is not smart enought to figure out that yPlusAValue involves the value ofy. As Svelte documentation mentioned:

reactive blocks are ordered via simple static analysis at compile time, and all the compiler looks at are the variables that are assigned to and used within the block itself, not in any functions called by them.

Now, let's port this to Preact Signal:

import { render } from "preact";
import { useSignal, useComputed } from "@preact/signals";

function Adder() {
	const x = useSignal(0);
	const y = useSignal(0);
	const total = useComputed(() => x.value + y.value)
  return (
    <div>
      <p>{x} + {y} = {total}</p>
      <button onClick={() => x.value++}>Increase X</button><br />
  		<button onClick={() => y.value++}>Increase Y</button>
	</div>
  );
}

render(<Adder />, document.getElementById("app"));

It is a bit more verbose than Svelte but still clean.¹ Most importantly, it also works with function calls:

function yPlusAValue(s) {
  return s.value + y.value;
}
const total = useComputed(() => yPlusAValue(x))

If only bandwidth is concerned, then:

• Serverless provides typically have a free plain, often with 100 GB free transfer per month. VPS provides usually have no free plan.

• The cheapest paid plan of both serverless and VPS provides often include 1 TB free transfer per month, but the cheapest VPS plan is usually cheaper than serverless.

• Overage is expensive compared to included transfer. Overage seems an afterthought for many serverless providers. They do not meter it, or handle it case by case, or enforce a soft limit, or charge a much more expensively, compared to VPS.

• Cloudflare offers a distinguished deal on bandwidth.

Comparison

Details

• Digital Ocean App Platform The starter plan (free) has 1 GB bandwidth per month, Professional 100 GB, and $0.10/GB for overage.

• Netlify Starter 100 GB, Pro 1 TB, and $55 per 100 GB for overage.

• Vercel Hobby 100 GB, Pro 1 TB, and contact the sale to buy additional bandwidth.

• Gatsby Free 100 GB, Professional 1 TB. Gatsby does not charge for overage, and they will contact the user if they continue to exceed bandwidth limits.

• Render 100 GB free, then $0.10 per GB.

• Koyeb 100 GB free, then $0.04 per GB (not charged yet).

• Railway 100 GB free for all the plans. Overage billing is not mentioned on their pricing page. And I suspect overage billing or throttling has not been implemented yet on their platform yet since I found this paragraph on their documentation:

  Railway doesn't meter bandwidth within Projects and the broader internet. As such, we have had projects handle unexpected traffic and features on major media publications. It is something we are very proud of. ... We do have plans to include private networking, static IPs, and allowing people to set up firewall rules to control permitted traffic within their projects.

• Fly 100/30/30 GB free for North America & Europe / Other / India, then $0.02/$0.04/$0.12 per GB. The price for 1 TB listed in the table above assumes bandwidth from North America or Europe.

• LeanCloud offers a free trial instance with 1 GB free bandwidth per day, then $0.1/GB for overage. The price listed in the table above assumes the site exceeds the free quota every day and there are 30 days in month. The free trial instance will hibernate if it has run more than 18 hours in the past 24 hours or no request is made in the past 30 minutes. The standard instance (no hibernation) costs $1.6 per day.

  BTW, bandwidth usage was unmetered until Novermber 2019.

• Heroku The Hobby plan is the cheapest one, costing $7 per month. Bandwidth is soft limited at 2 TB. Overage bandwidth billing is not mentioned on their site.

• GitHub Pages is free and there is a soft bandwidth limit of 100 GB per month.

• Cloudflare Pages features unlimited bandwidth. Use it for serving video or a disproportionate percentage of pictures, audio files, or other non-HTML content is against their terms though.

• Both Digital Ocean and Linode includes 1 TB bandwidth for the cheapest VPS plan. Additional transfer is billed at $0.01 per GB.

1. TypeScript is a superset of JavaScript.¹
2. TypeScript is JavaScript that scales.²
3. TypeScript is just JavaScript with types.³
4. TypeScript is JavaScript with syntax for types.⁴
5. TypeScript is JavaScript with types, unsound.⁵