Allow methods without docComment if comment does not provide additional value

susanne.moog (Susi Moog) 2017-09-20 14:24:05 UTC #1

Discussion Topic

Current CGL states that every method has to have a docComment / phpDoc - even methods without parameters or return types - for example constructors, resulting in comments like “constructor”. I’d like to propose to make the description part of the docComment (and thus the whole comment if no params/return type) optional to also get rid of simple getter/setter comments (what’s the benefit of the “get the ID” comment on top of a getId() method?).

Impact

CGL Adjustment to allow methods without comment

Pro

Less “noise”
Higher percentage of comments you should actually read

Con

Less strict rules, developers need to think about comment necessity (and content) more

Remarks and notes

Organizational

Topic Initiator: Susi Moog
Topic Mentor: Susi Moog

benni (Benni Mack) 2017-09-20 14:35:44 UTC #2

Hey,

same goes for class comments (when only “Class Package/ClassName” is stated), which could be removed as well - also for object properties:

One info worth mentioning is the proposal of PHP-FIG:

github.com

phpDocumentor/fig-standards/blob/master/proposed/phpdoc.md

PSR-5: PHPDoc
=============

## Table Of Contents

- [1. Introduction](#1-introduction)
- [2. Conventions Used In This Document](#2-conventions-used-in-this-document)
- [3. Definitions](#3-definitions)
- [4. Basic Principles](#4-basic-principles)
- [5. The PHPDoc Format](#5-the-phpdoc-format)
  - [5.1. Summary](#51-summary)
  - [5.2. Description](#52-description)
  - [5.3. Tags](#53-tags)
    - [5.3.1. Tag Name](#531-tag-name)
    - [5.3.2. Tag Specialization](#532-tag-specialization)
    - [5.3.3. Tag Signature](#533-tag-signature)
  - [5.4. Inline PHPDoc](#54-inline-phpdoc)
  - [5.5. Examples](#55-examples)
- [6. Inheritance](#6-inheritance)
  - [6.1. Making inheritance explicit using the @inheritDoc tag](#61-making-inheritance-explicit-using-the-inheritdoc-tag)

This file has been truncated. show original

neufeind (Stefan Neufeind) 2017-09-20 15:22:55 UTC #3

That php-doc-standard also just “recommends” using a DocBlock. That would allow us to interpret it as Susi suggests. I agree over-simple doc-blocks don’t help at all. Our PSR-standards also don’t forbid us to skip docblocks? (We wanted to stick to established standards, even if they might be unpopular).

Imho if we make it optional we will still be able to point out during code-reviews for which cases we definitely would want a docblock. We also currently check if the docblock makes sense or needs to be more precise/extensive/… So that should work out.

susanne.moog (Susi Moog) 2017-09-20 15:34:44 UTC #4

PSR-2 states:
“There are many elements of style and practice intentionally omitted by this guide. These include but are not limited to:
… Comments …”

shaak (Sebastian Haak) 2017-09-20 16:49:08 UTC #5

Hey,
I really appreciate the idea of leaving out unnecessary comments out. Right now, we often have the situation of comments for the sake of comments. They blow up the code and have no additional value.
However, I see the danger of lazy developers using that weaker rule as an excuse to stop commenting. But as Stefan says that could be caught at the code review.

Following Susi`s suggestion we would move close to one of the best practice rules of TheCodingMachine: http://bestpractices.thecodingmachine.com/php/design_beautiful_classes_and_methods.html#write-beautiful-phpdoc

liayn (Markus Klein) 2017-09-21 06:59:36 UTC #6

I fully support the proposal.

phpprof (Sebastian Michaelsen) 2017-10-12 11:24:53 UTC #7

Absolutely yes. It’s what we do (deliberately violating the TYPO3 CGL) in our projects already. Especially when you use the PHP7 style native type hinting for parameters and return types the phpDoc in many cases is completely useless.

richardhaeser (Richard Haeser) 2017-10-17 19:24:52 UTC #8

Yes please, but we really have to check in code reviews on missing docComments that do have value.

susanne.moog (Susi Moog) 2017-10-18 14:24:11 UTC #9

This topic was automatically closed after 28 days. New replies are no longer allowed.