in reply to Re: Re^6: Documenting Methods/Subs
in thread Documenting Methods/Subs

Part of the problem here is that your new could be improved.

Well, I was trying to keep the example simple :-)

After all, a later subclass could take as its logger argument either a Logger or a logspec, which can be used to build an appropriate logger. All of a sudden your assertion about the logger argument is incorrect.

In which case, I would change it.

My aim when I do this sort of thing is to make the assumptions (or contracts if you prefer) of my classes to be explicit. Where possible I like to make them explicit using code rather than comments or documentation.

If my contracts are wrong, I fix them. Having them in code makes it very obvious when they're wrong - which is a plus in my book :-)

Replies are listed 'Best First'.
Re: Re^8: Documenting Methods/Subs
by pdcawley (Hermit) on Jan 19, 2003 at 18:51 UTC
    After all, a later subclass could take as its logger argument either a Logger or a logspec, which can be used to build an appropriate logger. All of a sudden your assertion about the logger argument is incorrect.
    In which case, I would change it.
    Yick! I hate having to deal with dependent changes like that.

    Shall we agree to differ?

      Yick! I hate having to deal with dependent changes like that.

      To me it's not a "bad" dependent change. A documented (in code) design/implementation decision was incorrect. It needs to be fixed.

      Having these decisions explicit makes it easier (for me) to spot when they wrong.

      Shall we agree to differ?

      Okay doke :-)