Index, Count, Offset, Size

> When every variable that represents a byte quantity ends in _size and every item count ends in _count, a reviewer can spot dimensional mismatches almost mechanically

At that point I'd rather make them separate data types, and have the compiler spot mismatches actually-mechanically o.o

Canonical essay on this sort of technique: https://www.joelonsoftware.com/2005/05/11/making-wrong-code-...

u32AllocCount

u32AllocSumSizeInBytes

f32AllocAvgSizeInKBytes

Its easy to code review the interaction between these - the valid code almost writes itself from the names - lots of operations will just obviously read as wrong in ways that they may not with i.e. num_allocs, total_alloc and avg_alloc, or num, total, avg.

I find it useful to use statically typed variable names. My mental syntax checker benefits from the extra type metadata being embedded at each usage, reducing mental indirections/my reliance on the larger context and enabling me to quickly detect many types of mistakes via more efficient local reasoning.

> big-endian naming

I would call it “English naming” [0], it’s just more readable to start with, in an anglophone environment.

[0] as opposed to “naming, English”, I suppose ;)

I've always understood "length" to mean what the author calls "count", and would never expect it to refer to byte size; as far as I can tell, it never did. Size is a design-time consideration; caring about it in the code is an exceptional case, for applications like (as you mention) serialization. So that's what deserves the dedicated term. "Length" refers specifically to a total number of elements in many languages preceding Rust.

For that matter, many languages, especially "object-oriented" ones, treat heterogeneous containers as the default. They might not even offer native containers that can store everything inline in a single contiguous allocation, except perhaps for strings. In which case, "number of bytes" is itself ambiguous; are you including the indirected objects or not?

"Count" is also overloaded — it commonly means, and I normally only understand it to mean, the number of elements in a collection meeting some condition. Hence the `.count` method of Python sequences, as well as the jargon "population count" referring to the number of set bits in an integer. Today, Python's integers have both a `.bit_count` and a `.bit_length`, and it's obvious what both of them do; calling either `.bit_size` would be confusing in my mental framework, and a contradiction in terms in the OP's.

I would disagree that even C's `strlen` refers to byte size. C comes from a pre-Unicode world; the type is called `char` because that was naively considered sufficient at the time to represent a text character. (Unicode is still in that sense naive, but it at least allows for systems that are acutely aware of the distinction between "characters" and graphemes.) But notice: C's "strings" aren't proper objects; they're null-terminated sequences, i.e. their length is signaled in-band. So that metadata is also just part of the data, in a single allocation with no indirection; the "size" of a string could only reasonably be interpreted to include that null terminator. Yet the result of `strlen` excludes it! Further, if `strlen` is used on a string that was placed within some allocated buffer, it knows nothing about that buffer.

(Similarly, Rust `str::len` is properly named by this scheme. It gives the number of valid 1-byte-sized elements in a collection, not the byte size of the buffer they're stored within. It's still ambiguous in a sense, but that's because of the convention of using UTF-8 to create an abstraction of "character" elements of non-uniform size. This kind of ambiguity is properly resolved either with iterators, like the `Chars` iterator in Rust, or with views.)

Also consider: C has a `sizeof` operator, influencing Python's `.__sizeof__()` methods. That's because the concept of "size" equally makes sense for non-sequences; neither "count" nor "length" does. So of course "length" cannot mean what the author calls "size".

Big-endian naming is great. I've adopted it since I first read it about it in matklad's blog.

Ha! I also use `line_number = line_index + 1` convention!

Ordinal is nice because it explicitly starts at 1.

The reason many languages prefer `length` to `count`, I think, is that the former is clearly a noun and the latter could be a verb. `length` feels like a simple property of a container whereas `count` could be an algorithm.

`countof` removes the verb possibility - but that means that a preference for `countof` over `lengthof` isn't necessarily a preference for `count` over `length`.

When I see "countof" I expect an operation that lets me filter the container and tell me the count of things that meet some condition (probably described with a unary predicate, but perhaps just an element to check for equality).

I've never yet seen a linter option for assignment alignment, but would definitely use it if it were available

I know prettier can isolate a code section from changes by adding comments. And I think others can too.

See https://www.cs.utexas.edu/~EWD/transcriptions/EWD08xx/EWD831... for Dijkstra's thoughts on indexing.

Fortunately only a few. Djikstra's is obviously the most reasonable system.

When correctness is important I much prefer having strong types for most primitives, such that the name is focused on describing semantics of the use, and the type on how it is represented:

    struct FileNode {
        parent: NodeIndex<FileNode>,
        content_header_offset: ByteOffset,
        file_size: ByteCount,
    }

Where `parent` can then only be used to index a container of `FileNode` values via the `std::ops::Index` trait.

Strong typing of primitives also help prevent bugs like mixing up parameter ordering etc.

Long names become burdensome to read when they are used frequently in the same context

When the same name is used a thousand times in a codebase, shorter names start to make sense. See aviation manuals or business documentation, how abbreviation-dense they are.

When you’re juggling inputBufferSizeInBytes, outputBufferSizeInBytes, intermediateRepresentationBufferSizeInBytes, it becomes unwieldy and cumbersome.

I once had a coworker like that, whose identifiers often stretched into the 30-50 characters range.You really don’t want that.

Isn't that more tokens though?

I'm not sure what that has to do with the article, but anyway: https://www.cs.utexas.edu/~EWD/transcriptions/EWD08xx/EWD831...

That said, I'm not sure how 1-based indexing will solve off-by-1 errors. They naturally come from the fencepost problem, i.e. the fact that sometimes we use indexes to indicate elements and sometimes to indicate boundaries between them. Mixing between them in our reasoning ultimately results in off-by-1 issues.

When accessing individual elements, 0-based and 1-based indexing are basically equally usable (up to personal preference). But this changes for other operations! For example, consider how to specify the index of where to insert in a string. With 0-based indexing, appending is str.insert(str.length(), ...). With 1-based indexing, appending is str.insert(str.length() + 1, ...). Similarly, when it comes to substr()-like operations, 0-based indexing with ranges specified by inclusive start and exclusive end works very nicely, without needing any +1/-1 adjustments. Languages with 1-based indexing tend to use inclusive-end for substr()-like operations instead, but that means empty substrings now are odd special cases. When writing something like a text editor where such operations happen frequently, it's the 1-based indexing that ends up with many more +1/-1 in the codebase than an editor written with 0-based indexing.

This is a matter of opinion.

My opinion is that 1-based indexing really exacerbates off-by-one errors, besides requiring a more complex implementation in compilers, which is more bug-prone (with 1-based addressing, the compilers must create and use, in a manner transparent for the programmer, pointers that do not point to the intended object but towards an invalid location before the object, which must never be accessed through the pointer; this is why using 1-based addressing was easier in languages without pointers, like the original FORTRAN, but it would have been more difficult in languages that allow pointers, like C, the difficulty being in avoiding to expose the internal representation of pointers to the programmer).

Off-by-one errors are caused by mixing conventions for expressing indices and ranges.

If you always use a consistent convention, e.g. 0-based indexing together with half-open intervals, where the count of elements equals the difference between the interval bounds, there are no chances for ever making off-by-one errors.

I would bet that in the opposite circumstance you'd say the same thing:

"Is there any reason to not just switch to 0-based indexing if we could? Seems like 1-based indexing really exacerbates off-by-one errors without much benefit"

The problem is that humans make off-by-one errors and not that we're using the wrong indexing system.

Fundamentally, CPUs use 0-based addresses. That's unavoidable.

We can't choose to switch to 1-based indexing - either we use 0-based everywhere, or a mixture of 0-based and 1-based. Given the prevalence of off-by-one errors, I think the most important thing is to be consistent.

Because it is not how computers work. It doesn't matter much for high level languages like LUA, you rarely manipulate raw bytes and pointers, but in system programming languages like Zig, it matters.

To use the terminology from the article, with 0-based indexing, offset = index * node_size. If it was 1-based, you would have offset = (index - 1) * node_size + 1.

And it became a convention even for high level languages, because no matter what you prefer, inconsistency is even worse. An interesting case is Perl, which, in classic Perl fashion, lets you choose by setting the $[ variable. Most people, even Perl programmers consider it a terrible feature and 0-based indexing is used by default.

> Is there any reason to not just switch to 1-based indexing if we could? Seems like 0-based indexing really exacerbates off-by-one errors without much benefit

You'd just get a different set of off-by-one errors with 1-based indexing.

1-based indexing doesn’t work well as soon as you have a start offset within a sequence, from which you want to index. Then the first element is startIndex + 0, not startIndex + 1. 0-based indexing generalizes better in that way.

You say "seems like", can you argue/show/prove this?

In general in Rust, “length” refers to “count”. If you view strings as being sequences of Unicode scalar values, then it might seem odd that `str::len` counts bytes, but if you view strings as being a subset of byte slices it makes perfect sense that it gives the number of UTF-8 code units (and it is analoguous to, say, how Javascript uses `.length` to return the number of UTF-16 code units). So I think it depends on perspective.

It's the usual convention for systems programming languages and has been for decades, e.g. strlen() and std::string.length(). Byte length is also just more useful in many cases.

A length could refer to lots of different units - elements, pages, sectors, blocks, N-aligned bytes, kbytes, characters, etc.

Always good to qualify your identifiers with units IMO (or types that reflect units).

> or is it just Rust just being confusing?

It doesn't mean "byte length", so much as "byte" happens to be the element type. Unicode is conventionally represented as UTF-8, so the container can't be directly indexed to yield a character.

I was thinking sql.

Looks perfect here. iOS Safari