Add phpdoc_summary PHP CS Fixer rule

[aleksip]

No description provided.

[demiankatz]

Thanks for giving this a try, @aleksip. I have somewhat mixed feelings about the results. I definitely like having punctuation on function header comments, which are generally a sentence. However, it looks weird in other places where the comment is not a sentence (e.g. "Constructor" --> "Constructor." or property header comments that simply describe what things are without using full sentences).

Obviously, I realize that an automated style rule can't possibly differentiate between these cases, so if we decide to go forward with this, we'll need to live with the consequences. I just wonder if this is a time to think about best practices and consider changing our approach to anything.

I'll leave this one open for a while so it can collect thoughts and opinions; it's probably worth discussing on the next Community Call!

[aleksip]

Personally I don't find the full stops in the cases you mentioned as disturbing as the unavoidable inconsistency when there is no no automated rule at all. So I would be in favour of adding the rule, but this is definitely not a hill I want to die on.

[demiankatz]

@aleksip, I'm inclined to agree that consistency is better than inconsistency, even if some instances of the consistent approach might be less desirable. However, there might be some things we could do to mitigate the problem (e.g. should we change every instance of * Constructor. to * Construct the object.?). In any case, I think a community discussion before merge is a good idea, so people have an opportunity to share ideas/opinions, and so nobody is surprised if their existing PRs suddenly fail builds because of missing punctuation. :-)

[aleksip]

@demiankatz Yes, I agree 100 % on having a community discussion.

[demiankatz]

@aleksip, I've started building the March Community Call agenda and have included this so we don't forget.