Comment style for Enum

Do we even need this issue? 😅 Can't we assume that inline comments are allowed in any PHP class, whether or not it's an enum? I'm inclined to say we don't need the whole formal process for this change, and we should configure the sniff to optionally allow for comments. But if we need the formal process for this, I'm formally a supporter now. 😂

Thanks,
-Derek

I do think we need an issue because of the variety of implementations in core, which I have added to the issue summary.

We should be able to say, at least, if a blank line is required between cases whether a comment is present or not.

Shouldn't enum cases have docblocks rather than line comments, the same as class constants and properties do?

+1 to #4 if we must have documentation on the cases. I'm not really a fan of the proposed solution, though, unless it can be optional like constructor parameters or even as discussed in 📌 Allow omitting doxygen when type and variable name is enough Active .

Going with the example on phpwatch, I think an enum like this is fine:

enum Suit {
    case Clubs;
    case Diamonds;
    case Hearts;
    case Spades;
}

If we're forced to document obvious enums like the above, then we're back to square one.

+1 to allowing optional comments.
+1 to allowing those comments to be formatted as a formal docblock if needed for something.
+ 1 to allowing optional new lines where appropriate for legibility.
-1 to requiring comments.
-1 to requiring comments to be formal "docblock" style. Inline should be fine in the majority of cases.
-1 to requiring newlines.

Using the simple style from @dww

+1 to allowing optional comments.
+1 to allowing those comments to be formatted as a formal docblock
+ 1 to allowing optional new lines where appropriate for legibility.
-1 to requiring comments.
+1 to requiring comments to be formal "docblock" style.
-1 to requiring newlines.

We should have one comment style instead of 3, that isn't done anywhere else.

Shouldn't these be long docblocks, the same as class properties?

enum Exists {

  /**
    *  Throw an exception when the entity exists.
    */
  case ErrorIfExists;

+1 to allowing optional comments.
+1 to allowing those comments to be formatted as a formal docblock
+ 1 to allowing optional new lines where appropriate for legibility.
-1 to requiring comments.
+1 to requiring comments to be formal "docblock" style.
-1 to requiring newlines.

The comments so far are in favor of optional comments, using doc block style, new lines as needed. I have updated the proposal resolution with that.

I'm a big -1 to requiring doc blocks. Having one line comments makes scanning enums with many cases much easier. It would add a lot more scrolling if a Dev wanted to document each case but was forced to use doc blocks.

+1 to allowing optional comments.
+1 to allowing those comments to be formatted as a formal docblock
+ 1 to allowing optional new lines where appropriate for legibility.
-1 to requiring comments.
0 to requiring comments to be formal "docblock" style.
-1 to requiring newlines.

+1 to allowing optional comments.
+1 to allowing those comments to be formatted as a formal docblock
+ 1 to allowing optional new lines where appropriate for legibility.
-1 to requiring comments.
0 to requiring comments to be formal "docblock" style.
-1 to requiring newlines.

-1000% for requiring comments.

Noting that Symfony, has chosen this also. But it doesnt seem to be enforced by rulesets.

Expanding on new lines. New line before comment, so long as there is a comment. Otherwise enums bumping into eachother is allowed.
And new line after and before the enum brace, same as classes.

More importantly, enums should be self explanatory. Or otherwise easily explainable by an optional class-level/top-level comment.

/**
 * Optional comment.
 */
enum Thing {
  
  case Foo1;
  case Foo2;
  case Foo3;
  
  /**
   * Description.
   */
  case Foo4;
  case Foo5;
}

We currently have 4 supporters of doc style and 4 against the style.

Just trying to see what it could look like if inline comments are used instead of a doc block in the unlikely case of multi line comments.

enum Exists {

  /**
   * Throw an exception when the entity exists.
   *
   * Can add more information here. The quick brown fox jumped over the lazy
   * dog.
   */
  case ErrorIfExists;

  // Throw an exception when the entity exists.
  // 
  // Can add more information here. The quick brown fox jumped over the lazy
  // dog.
  case ErrorIfExists;

  // Throw an exception when the entity exists. Can add more information here.
  // The quick brown fox jumped over the lazy dog.
  case ErrorIfExists;

  // Do stuff. 
}

Re #14 - I think doc blocks are still the right approach for multiline comments. But inline comments are the right approach for 1 line comments.

For the core FileExists enum, we currently have this (8 lines)

enum FileExists {

  /* Appends a number until name is unique. */
  case Rename;
  /* Replace the existing file. */
  case Replace;
  /* Do nothing and return FALSE. */
  case Error;

Enforcing doc blocks + new lines it'd be (16 lines, double the current line count)

enum FileExists {

  /**
   * Appends a number until name is unique. 
   */
  case Rename;
  
  /**
   * Replace the existing file. 
   */
  case Replace;
  
  /**
   * Do nothing and return FALSE. 
   */
  case Error;

Allowing inline comments would keep the line count at 8, or if we want to enforce newlines between inline commented cases it would be 10.

Doubling the number of lines in a 3 case enum doesn't seem worthwhile when it doesn't improve the readability (IMO). For Enums with more cases this gets compounded further.

I thought I'd chime in to clarify why I'm undecided on requiring comments to be formal "docblock" style. I think that enum case names should generally be self documenting, but in the case that they need further explanation they probably should have a thorough, well thought out comment. But perhaps there are cases where a single-line comment is fine (e.g. the existing FileExists comments). Ultimately I think it's probably better not to be prescriptive about this, so changing my vote to -1.