TYPO3.Kickstart

Patch set 2 for branch master has been pushed to the review server.
It is available at https://review.typo3.org/20596

Patch set 3 for branch master has been pushed to the review server.
It is available at https://review.typo3.org/20596

A little "pleading" against automatic (doc) comments:¶

The only situation where I would be in favor of a kickstarter adding comments is where it would be clever enough to add meaning (e.g. by determining the mechanics/domain logic behind a function so that it can be explained more comprehensible than the actual code).
I doubt that this is possible because A: the kickstarter would have to very very clever and B: at the stage of kickstarting "dumb" code, there is not much meaning to explain (apart from the technical workings which are the same for all MVC apps).

This is the code the kickstarter currently generates for domain models:

 1/**
 2 * A Beer
 3 *
 4 * @Flow\Entity
 5 */
 6class Beer {
 7
 8    /**
 9     * The name
10     * @var string
11     */
12    protected $name;
13
14    /**
15     * Get the Beer's name
16     *
17     * @return string The Beer's name
18     */
19    public function getName() {
20        return $this->name;
21    }
22
23    /**
24     * Sets this Beer's name
25     *
26     * @param string $name The Beer's name
27     * @return void
28     */
29    public function setName($name) {
30        $this->name = $name;
31    }
32
33}

I think the following is exactly as meaningful:

 1/**
 2 * @Flow\Entity
 3 */
 4class Beer {
 5
 6    /**
 7     * @var string
 8     */
 9    protected $name;
10
11    /**
12     * @return string
13     */
14    public function getName() {
15        return $this->name;
16    }
17
18    /**
19     * @param string $name
20     * @return void
21     */
22    public function setName($name) {
23        $this->name = $name;
24    }
25
26}

Obviously I'm not against doc comments at all! But I doubt that they are something the computer can take over (apart from annotations of course).

Boilerplate comments won't encourage developers to explain themselves¶

Lets face it, there are two kinds of developers: Those who care about doc comments and those who don't.
IMO we can't really change this (apart from giving a good example in the framework code). I've seen so much code already where doc comments still referred to the copied function, property or even package – this is rather counter-productive.

So I think it's the other way around: devs are discouraged to adjust doc comments if everything looks "fine". That's why I even suggest to leave out class doc comments (apart from annotations) – it's not worse than a wrong doc comment and a decent IDE (e.g. PhpStorm) will highlight the line with a "Missing PHPDoc comment" warning (depending on the inspections settings).

+1 to the plead ;)

+1 from me as well.. do this already personally

+1