2

How to tag preconditions with PHPDoc? I have an object, and before calling a function another function must have been called:

$myObject = new MyClass();
$myObject->mustDoThis();
$myObject->beforeThis();

So the documentation for beforeThis() would look like:

/**
 * @precondition mustDoThis() must be called before this function is
 */

Or is there another way around this? Perhaps a @throw clause would be enough.

Olle Härstedt
  • 3,799
  • 1
  • 24
  • 57

2 Answers2

2

As far as I know, there's no standard @precondition or @postcondition tags for PhpDoc but I use them anyway as it is a nice way to hint the developer implementing the class/interface/trait.

Flatline
  • 1,036
  • 1
  • 10
  • 17
  • `@see` is probably the best "standard" way for each method to link to the other. The description portion of the tag would then describe what their relationship is. – ashnazg May 27 '14 at 21:38
0

According to the book "Clean Code" written by Robert C. Martin, the scenario you have described is a temporally coupled pair and you should solve it by making a new method which calls those methods in the right order.

The client shouldn't know in which order should call methods so encapsulate the logic.

Ungureanu Alexandru
  • 1
  • 1
  • Your answer could be improved with additional supporting information. Please [edit] to add further details, such as citations or documentation, so that others can confirm that your answer is correct. You can find more information on how to write good answers [in the help center](/help/how-to-answer). – Community Jan 21 '23 at 11:53