Question about adding !function_identifier

I think the issue here is that there is no functional difference between an exclamation mark prefix and a docblock attribute, and the latter has the advantage of being more explicit, not requiring changes to the language syntax itself, and being an already-existing standard.  Of course things may move around during the development process, but I don't really see how you can't move around the docblocks with the functions they belong to... A decent IDE will make this easy and can also use the @throws tag to provide the contextual information you're looking for, again, without having to change the language itself. Best, Stijn Op 3 april 2019 bij 18:52:58, M. W. Moe (mo.mu.wss@gmail.com) schreef: Hello, not documenting at first is not really a question of laziness or so, as things are still moving around you absolutely need this agility; a good design layout between theory and stable state will refactored discussed a thousand times; that what I expect from engineers; filling the gaps between assumptions and reality. And for me-self throw vs no throw is important language information and part of internal behaviors; to clarify, for instance, would be more useful to have such indicator rather than having having abstract and interface which are cumbersome; same as the extra public keyword; you can do without especially with the new traits construct. Best. On Wed, Apr 3, 2019 at 9:42 AM Rowan Collins <rowan.collins@gmail.com> wrote:

If you’re unwilling to write a docblock for some good reason, why not just use the built-in, user-extensible way that most programming languages have to add annotations without runtime effect, namely unstructured comments? Something like /* nothrow */ is both forward- and backward-compatible... Am I missing something? —Claude

On Wed, 3 Apr 2019 at 17:52, M. W. Moe <mo.mu.wss@gmail.com> wrote:

I think we have different assumptions about what "documentation" means here. I'm not saying you have to write a 500-word paragraph explaining the theory and edge-cases in the code; just that you should write a quick comment saying what the function expects, and what it will return, beyond the ability of the language's syntax. You *could* write every function like this: function tbc(...$args) { } That way, you can change the visibility, the argument types, the return types, and the name, without "documenting" it in advance. Clearly, that would be ridiculous, so you probably actually write this: public function convertFooToBar(Foo $foo): Bar { } What I mean by "documentation first" is to go a small step further and write: /** * Convert using the lookup tables * * @param Foo $foo Should only be given pre-validated Foo * @return Bar Will always be pre-validated * @throws InvalidFooTypeException */ public function convertFooToBar(Foo $foo): Bar { } This is all part of the *current* design of this function. It might change, but if it changes, you change the docblock, just as you'd change the signature if you realised it should actually be private, or accept a PreValidatedFoo object, or the name is wrong. You seem to want to do this same job, but with as few characters as possible, and I don't really understand why, if your aim is to be explicit and clear. If you just want to type less, use an IDE or editor with good auto-complete support. Regards,