Hello,
quick commenting usually ends up in a `circus`; either you enforce extra
qualifiers in term of signature or you don't encourage it
you seems not having the experience of working on the same code base with
basically literally dozen of people which can at
some point intervene; this is reality, this not wrong or bad; you deal with
it.
We are a shop where people are using terminal emulators; vim or emacs not
cumbersome IDEs or for some not even a window manager
; reality; you deal with it. Moreover an exception state is not really like
a status; this is an internal language behavior, should
be carried by the syntax even if informal, anyhow could evolve over time.
On Wed, Apr 3, 2019 at 10:24 AM Rowan Collins <rowan.coll...@gmail.com>
wrote:
> 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]
>
