Proposal: todo

[matklad]

TL;DR

Introduce a new expression, todo, which is coercible to any type, traps at runtime in any build
mode, and is used to communicate incomplete code which is being actively authored right now:

pub fn eval(op: Op, lhs: u64, rhs: u64) i64 {
  return switch (op) {
    .add => lhs +% rhs,
    .sub => lhs -% rhs,
    .mul => lhs *% rhs,
    .div => if (rhs == 0)
      todo // Figure out how to signal division by zero.
    else
      lhs / rhs
  };
}

Proposed todo is a bit like undefined, and a bit like unrechable, but clearly communicates
that the code itself is incomplete.

Motivation & Use Cases

Direct Use

The simplest case is for direct usage by the programmer when they write code! It's hard to
write everything right from start to finish, often it is useful to spike only the central use-case
and happy path, and just "stub out" all the more tricky cases. Today, you can use unreachable or
@panic("todo") for this use-case, and they work OK. However, unreachable can be confused with
intentional unreachable, and @panic("todo") is a pain to type. While optimizing typing is not
the goal in general, when you are spiking out solution it becomes relatively more important.

Another subtle point is that unreachable and @panic() are typed as noreturn, but occasionally
you want to type something like

const x: Thing = todo;
x.frobnicate();

and get compilation erros for the code with follows.

todo is simple to type, simple to delete, and unambigious.

"IDEs"

The primary motivation comes from "IDE" land. IDEs offer various automated refactors, and very
often you want to explictly mark parts of the code to be filled-in by the user. For example,
returning to the original example, a typical IDE feature would be for the user to type
return op.switch, mash tab key, and get that exanded to

return switch (op) {
  .add => todo,
  .sub => todo,
  .mul => todo,
  .div => todo,
};

Again, an IDE can generate @panic("todo"),, but then it'll be harder to replace for the user (due
to ,, just dW won't work).

Depending on how deep you want to go into the IDE-land, you can imagine strctural-editing-like
experience, where if exands to if (todo) todo else todo, and then tab key cycles through
todos. In general, explicit todo makes building something like
hazel, but text easier.

Again, this is not a deal breaker, @panic("todo") would work ok, but todo would be nicer.

Resilitent Compilation

In some sense this is a continuation of the previous use-case, but interally, and IDE might want
to be resilient to compilation errors. To provide type-guided features in downstream code, an
IDE-concious compiler might want to treat erroneous code const x = xs.no_such_method() like
const x = todo;. Having an explicit todo makes that sort of desugaring more natural! Note, however, that implementing resilient compilation is explicitly out of scope for this proposal.

Proposal

Add a todo expression, which behaves like a cross between undefined and @panic():

• Like undefined, todo is typed using RLS, it is not noreturn.
• But, like @panic, undefined is guaranteed to generate a trap.
• Unlike both, it is runtime-known.

todo can desugar as

if (runtime_true()) @panic("todo") else undefined

where runtime_true is just an anti-comptime barrier:

fn runtime_true() bool { return true; }

Here's a todo test:

pub fn todo_test() []const u8 {
    const x = todo;
    const y: i32 = todo;
    todo;
    @as(std.time.Timer, todo).reset();
    return todo;
}

This function should compile succesfully. Notably, it shouldn't give "unreachable code" errors.
At runtime, under any optimization mode, it should trap when evaluating const x = todo.

[linusg]

Prior art (later reverted): #5641, #10306

Side note: it looks like Andrew is ok with this proposal but as per https://github.com/ziglang/zig/wiki/Language-Proposals a core member should have filed it.

[gyreas]

a typical IDE feature would be for the sure to type

Unnecessary typo nit, on "sure", you meant "user"?

[scottredig]

Depending on how deep you want to go into the IDE-land, you can imagine strctural-editing-like
experience

To reinforce this point with some data, I spent some time last year attempting to write a structural code editor for Zig. It's been awhile since I touched the project, but to my recollection I had identified three challenges while digging in how to do it:

1. Poor support for incomplete edits being valid parses of the ast.
2. Comments are valid in too many places.
3. Lack of language level extensibility for a feature I wanted to add on top of the structural editing.

I think this issue would go a long way towards resolving the first point. I don't know if todo would solve it all, as this is an issue you hit so quickly that I never fully looked at the full scope of the problem. As a simple example, imagine creating a new file, starting to write a function; then before you give it a return type, save the file, close it, then re-opening it in the editor. If you're doing a pure text editor, it will happily save and then open a file who's contents are only fn main(). However the ast based editor would not be able to resolve this. I was thinking of saving it as something like fn main() _ {}, but I never got far enough to see if that would resolve the issue. I believe having todo would both make these structural edits have an obvious solution, and integrate with the compiler more cleanly (especially for making compiler errors understandable).

Less relevant asides:
For the second issue, I was going to propose only allowing comments where a newline would otherwise be kept by zig fmt. You can force new lines to be in all sorts of wacky places in Zig, simply by putting a comment there. This was annoying in the ast editor, because comments interact with the ast in a way that never happens with the compiler, as the compiler simply strips them out. So, eg,

pub fn main() void {
	if // why is this comment allowed 
	(true) {}
}

is valid and correctly formatted Zig. So suddenly your ast editor when editing the if node needs to give you access to this weirdly positioned comment. It also can expand the number of comments to beyond 1 per ast node, which is annoying from a data structure point of view.

The third issue is something I don't expect the Zig project to care about. Just some crazy ideas about programming I have. I briefly started writing a toy compiler which would support it, decided that's not how I wanted to spend my time, and then got distracted by gamedev. I might come back to this and push to see if it's actually a requirement or not.

In general, explicit todo makes building something like
hazel, but text easier.

I'm fairly convinced at this point that text is the correct backing data structure and save format for ast editing, for a variety of reasons.

[rohlem]

Original comment summarized:

The noreturn type of unreachable and @panic is not the issue;
noreturn already coerces to every possible type,
so even the proposed todo should probably be typed noreturn (or @TypeOf(undefined)).

EDIT2: Playing around with it more,
it seems like if(true) unreachable suppresses the compile error for unreachable code | control flow diverted here in runtime code,
but still doesn't continue analysis.
So I learned something new today.

[mlugg]

@panic("todo") is a pain to type

I tend to just write @panic(""). About the same number of keystrokes as unreachable, and easy to find.

I also sometimes write "TODO" in the (common) case where something isn't a string; I can search for "TODO" and I'll get a compile error if I leave it there, win-win!

todo can desugar as

if (runtime_true()) @panic("todo") else undefined

This isn't a workable definition, for instance:

var x = todo;
// you clearly want that ^^ to work
// but:
var t: bool = undefined;
t = true;
var x = if (t) @panic("todo") else undefined;

foo.zig:4:9: error: variable of type '@TypeOf(undefined)' must be const or comptime
    var x = if (t) @panic("todo") else undefined;

More generally, the point is that this definition is not runtime-known, and in the case where there isn't a result type it can't be because @TypeOf(undefined) is comptime-only.

I think you underestimate the complexity that this feature would entail. To prevent bogus compile errors / LSP type information, but without terminating compilation, todo would need to result in a new value of a new type. That value I think also needs to have a variant that is a type, to deal with e.g. const x: todo = .... Then, literally every part of semantic analysis needs to become aware of this new kind of value, in every context where any comptime-known value -- or any type -- is used. There are two ways I can see of doing this:

• The "direct" approach where you actually do this work on every operation in Sema. I think that this would add 2-3 thousand lines of cruft to Sema touching almost every function in it, and forgetting to do the checks anywhere -- which people would for sure forget -- would result in potential compiler crashes.

• A more generalized approach where for the most part, functions like Sema.typeOf and Sema.resolveValue notice the "todo" case and return some error.HitTodo which is pushed up the stack and handled by Sema's main loop. Assuming this is viable, it would certainly be a smaller diff, but it would likely have compiler performance implications (we are already aware of existing performance impacts from unnecessary work in the resolveValue path, and typeOf is far more common than resolveValue).

This complexity doesn't rule out the feature, but it does make me strongly biased against it. I think it will need some very strong justification to be worth considering, and I definitely do not think this proposal contains such justification. Let me analyze the three listed arguments.

Direct Use

You can always do:

fn todo() noreturn {
    @panic("reached todo");
}

Of course, this wouldn't give you compilation errors for code following a todo() call; I'll touch on this below.

"IDEs"

As well as your suggested @panic("todo"), {}, // TODO, etc are all perfectly fine options for an IDE to auto-fill in here. If it can't easily jump between them, that sounds to me like an IDE deficiency; when it auto-generates "holes", it should have a way for the user to specify what those "holes" should be. I don't think Zig should be designed to accommodate missing code navigation features in otherwise sophisticated IDEs.

Resilitent Compilation

Okay, here's where I expand on "getting compile errors after todo", and the general concept of continuing semantic analysis when "something is wrong".

I really hate when compilers and LSPs do this kind of thing, because at best I do not benefit from it, and at worst I spend a lot of time confused by incorrect information.

One of the things I find refreshing about Zig is that the compilation errors it shows are pretty much always the actual problem; I can pick a random item in the error bundle and fix it. Perhaps it'll make one or more extra errors appear because more code gets analyzed, but that's not actually a problem; I'm already fixing a bunch of compile errors, it's fine if that work is a bit bigger than I thought. In contrast, C++ compilers have an awful habit of giving me utter crap after the first error in a file, so I have to scroll up to said first error; everything after it is potentially useless. If I ever forget this fact, I waste a lot of time trying to debug weird cryptic (as in, cryptic even for C++!) errors. C is better in this regard -- in fact I am often quite impressed with C compilers' error recovery -- but it can absolutely still suffer from this issue (particularly when the preprocessor is involved). I find that attempts at "error tolerance" in other language decrease my productivity and increase my frustration, not the other way around.

Okay, so, let's say you don't show compile errors after the first error, but you still do semantic analysis, so you can give type information to an LSP. The type information isn't guaranteed to be correct -- the presence of broken or incomplete code pretty much guarantees that you can't understand the user's intent -- but it'll be best-effort. I still find that such features hurt far more than they help, pretty much for the reason reasons. I don't use LSPs very often, but I did in the past (I think the most recent thing I seriously used an LSP for was Typescript?), and this feature was infuriating every time I actually interacted with it; type information after compile errors had a fairly high chance of being wrong, but dammit the compiler was still going to try, and that led me down silly rabbit-holes on multiple occasions. And I ask again... for what? What actually makes this feature particularly compelling? If you have a compile error in code you've just written, just quickly fix that first; then the compiler can continue to help you down the line with 100% accuracy! The alternative is you still need to fix that compile error eventually, but in the meantime, you might get tricked by an incorrect inference. Perhaps we could design the compiler to make those incorrect inferences really rare -- but personally, I would prefer that the design makes them entirely impossible, and by far the best way to do that is to say that analysis errors block further analysis.

In short... If the compiler isn't certain what I mean, it's not its job to guess. It'll probably get it wrong.

If you do want this feature, I would suggest that it should ultimately be provided by a third-party project. This suggestion does not conflict with #615. I think it makes sense for the #615 server to serve "correct" information given valid source code, and that the "bridge" project which calls into it can adjust the provided source code if it wants to somehow guess at the user's intention to get more semantic information at the cost of potential incorrectness. This is more versatile, particularly since it doesn't tie the specific heuristic to the Zig compiler implementation, which would probably be undesirable.

---

TLDR: I don't think the complexity of this feature in implementation terms (and in fact, specification terms too, because its impact on type inference and semantic analysis would need to be strictly specified!) is at all justified by the listed use cases. Simple "todo" placeholders feel perfectly adequately solved today. IDEs should be able to navigate through any placeholder they insert regardless of Zig's syntax. Resilient compilation is not an objectively desirable feature -- I find it useless at best and highly frustrating at worst -- but if you do want such a feature, I would argue that it is the job of a third-party project (which can send its "guess" to the Zig compiler to get type information).

[matklad]

Apologies for writing an unclear proposal, I definitely do not mean to suggest here that zig compiler should go all the way to resilient compilation. For resilient compilation in general, my current set of beliefs is 0.1 that using last valid compilation would be enough, 0.3 that zig compiler will grow support for resilience and, 0.6 that there will be a second zig compiler front-end for LSP use-cases.

The proposal is intended to be strictly scoped to if (runtime_true()) unreachable else undefined desugaring, which shouldn't be hard to implement. In particular, I don't think that is required that const x = todo and var x = todo work, it's fine for either or both of them to fail compilation (but I didn't realize that there might be a difference between const and var here, thanks for pointing that out).

It is desirable for const x: todo to be syntactically valid, and Zig gets that for free by virtue of not making distinction between type, pattern, and expression grammars. But it doesn't have to have any runtime semantics, failing the compilation there is ok!

Ultimately, what is proposed here is a small feature, for only a marginal improvement. On the pure cost-benefit tallying-up, I would say that we clearly don't need it. However, what bugs me personally on more amorphous aesthetics grounds, is that incomplete code is such a clear use-case, and that not having a first-class feature to express it feels like a hole in the language (pun was not indented, lol).

Let me also note that the proposal is descriptive, not prescriptive: there's a todo use-case, and here's how it could be served. I do not claim that we must serve use case. I do claim that whatever we chose here, it's going to be a small mistake either way :)

[IntegratedQuantum]

if (runtime_true()) @panic("todo") else undefined

I think there are some other, simpler user land options worth exploring here, one option would be optionals:

fn todo() ?noreturn { // Ideally we'd have @TypeOf(undefined), but sadly that's a comptime-only type making the whole function comptime.
    if(true) @panic("TODO");
    return null;
}
const x: i32 = todo() orelse undefined;

Another option which might be even more practical and looks quite readable too, is just manually passing the type:

fn todo(T: type) T {
	@panic("TODO");
}

pub fn todo_test() []const u8 {
    const x = todo(type);
    _ = x;
    const y: i32 = todo(i32);
    _ = y;
    todo(void);
    todo(*std.time.Timer).reset();
    return todo([]u8);
}

And it's less characters than @panic("") even

[scottredig]

Small addition: Something that a special keyword could do, that @panic("TODO") couldn't do is suppress unused variable in that scope.

Consider

fn foo(bar: *Bar) Baz {
  todo;
}

vs.

fn foo(bar: *Bar) Baz {
  _ = bar;
  @panic("TODO");
}