Code That Says Exactly What It Means

[Steven Schveighoffer]

On Friday, 31 October 2025 at 00:50:54 UTC, Walter Bright wrote:
> On 10/29/2025 8:48 PM, Steven Schveighoffer wrote:
>> There has always been only ONE deficiency for this, and that 
>> is documented unittests being allowed to use private symbols 
>> in the module. But this is a unittest problem, and not a 
>> private problem.
>> 
>> Note that the OPs argument against (non-documented) unittests 
>> being able to access private data is ironically something I 
>> view as a necessity -- I often test functions on a type and 
>> then examine the private details to make sure the state is as 
>> I expect it.
>
> Since unittests aren't part of the finished program, preventing 
> it from having access is not terribly useful. It's like you can 
> prefix statements with `debug` when needing to override pure / 
> @safe attributes.

I've already started replying again, even though I said I 
wouldn't, but this is an important point to get right, Walter. I 
agree normal unittests should be able to access private members, 
I said as much in the second paragraph above.

What we are talking about is *documented* unittests.

Consider the following documented unittest:

```d
private int foo(int x) => 2 * x;

/// Do some interesting stuff
public int doStuff() => 42;

/// How to use doStuff
unittest {
    auto val = doStuff();
    assert(foo(val) == 84);
}
```

Now, what happens here is that the ddoc system will show the 
documented unittest for `doStuff` in the documentation for it.

But it has used a private function! The user has to go look at 
the source code of the module, to understand what `foo` actually 
does, to undestand what `doStuff` actually does.

The point of a documented unittest is to show to a user how a 
function works. If it is using private undocumented symbols, then 
the user is clueless as to what it means.

So my recommendation would be to either ban private symbol use in 
documented unittests, or to provide a mechanism to allow 
unittests to be banned from using private symbols (maybe `public 
unittest`? I don't know)

Note that we had problems with code on dlang.org for years on 
this front, and it was finally solved by writing a tool that 
parses d code, and outputs all the unittests as external 
functions to ensure they aren't using private symbols.

See the code here: 
https://github.com/dlang/tools/blob/master/tests_extractor.d

It would be very nice if we didn't have to do this extra step.

-Steve