On Wed, 3 Apr 2019 at 17:52, M. W. Moe <mo.mu....@gmail.com> wrote:
> 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.
>
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,
--
Rowan Collins
[IMSoP]
