This question is really based on PHP, but could be valid for other dynamically typed, interpreted languages and specifically the methods of generating code insight and object browsing in development environments.

We use PHPStorm, and find intellisense invaluable, but it is provided by some limited static analysis and parsing of doc comments.

Obviously this does not lend well to obtaining dependencies through a container, as the IDE has no idea of the type returned, so the developer loses out on a plethora of (in the case of our framework anyway) rich documentation provided through the doc comments.

So we start to see stuff like this:

$widget = $dic->YieldInstance('WidgetA', $arg1, $arg2, $arg3, $arg4...));
/**
 * @var $widget WidgetA
 */

So that code insight works.

In effect the comments are tightly bound, but worse they come out of sync when code is modified but not the comments:

$widget = $dic->YieldInstance('WidgetB', $arg1, $arg2, $arg3, $arg4...));
/**
 * @var $widget WidgetA
 */

Obviously the comment could be improved by referencing a Widget interface, but then we might as well use a factory and avoid the requirement for the extra typing hints in the comments, and dic complexity / boiler plating.

Which is more important to the average developer, code insight / intellisense or 'nirvana' decouplement?