Bug #48030

Kickstarter creates superfluous code

Added by Bastian Waidelich over 8 years ago. Updated over 8 years ago.

Status:
Resolved
Priority:
Should have
Start date:
2013-05-07
Due date:
% Done:

100%

Estimated time:

Description

The kickstarter creates a lot of code that is not needed (especially redundant doc comments)

#1

Updated by Gerrit Code Review over 8 years ago

  • Status changed from Accepted to Under Review

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

#2

Updated by Gerrit Code Review over 8 years ago

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

#3

Updated by Gerrit Code Review over 8 years ago

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

#4

Updated by Bastian Waidelich over 8 years ago

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:

/**
 * A Beer
 *
 * @Flow\Entity
 */
class Beer {

    /**
     * The name
     * @var string
     */
    protected $name;

    /**
     * Get the Beer's name
     *
     * @return string The Beer's name
     */
    public function getName() {
        return $this->name;
    }

    /**
     * Sets this Beer's name
     *
     * @param string $name The Beer's name
     * @return void
     */
    public function setName($name) {
        $this->name = $name;
    }

}

I think the following is exactly as meaningful:

/**
 * @Flow\Entity
 */
class Beer {

    /**
     * @var string
     */
    protected $name;

    /**
     * @return string
     */
    public function getName() {
        return $this->name;
    }

    /**
     * @param string $name
     * @return void
     */
    public function setName($name) {
        $this->name = $name;
    }

}

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).

#5

Updated by Rens Admiraal over 8 years ago

+1 to the plead ;)

#6

Updated by Aske Ertmann over 8 years ago

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

#7

Updated by Christian Müller over 8 years ago

+1

#8

Updated by Bastian Waidelich over 8 years ago

  • Status changed from Under Review to Resolved
  • % Done changed from 0 to 100
#9

Updated by Gerrit Code Review over 8 years ago

  • Status changed from Resolved to Under Review

Patch set 1 for branch 2.0 has been pushed to the review server.
It is available at https://review.typo3.org/20966

#10

Updated by Bastian Waidelich over 8 years ago

  • Status changed from Under Review to Resolved

Also available in: Atom PDF