Docblock comments and more in code guidelines / standards

In the recent WordPress Coding Standard discussion it was clear that mutliple scenarios are not handeled. While doing more and more WP developmet these days, the list of stuff grows so it’s good to collect and to write them down. The followinig list contains those from my recent summary post, the discussions in comments here and there and things I did run over with other developers while handling patches within the last week:

  • Comments: Write constants in comment UPPERCASE or lowercase? Generally it’s an idiom to write constants all uppercase.
  • Comments: Optional variables. There are different notations on how to flag a variable optional with the @param notation. Two I found within the code were (optional) and Optional.
  • Comments: @since version numbers. Since version 1, three dotted version numbers are used (e.g.) 1.5.0, but sometimes you see 2.8 instead of 2.8.0
  • Comments: Indentation after @tags and previous to their value. Sometimes it’s aligned, sometimes not. Aligned is better to read, but is it the criteria?
  • Code Organisation: External files should be properly flagged as those, so it’s clear thatWordPress Coding Standards do not apply to those. A specification how this is done in the project is needed.
  • Whitespaces in the brackets on class instantiation with the new operator. Are those to be handeled like function calls?
  • !empty( $blah ) or ! empty( $blah )? The first is w/o the second with a space after the exclamation mark.
  • Should translation functions follow the rules defined for functions or should there be exceptions for certain functions? But question could be, if it won’t work for every function, why to we do it then?
  • array brackets. put spaces in there as well, like $array[ $key ]?
  • case with space? like case 'all' :?

I might extend this list for new issues I run over or I read about in the discussions. If you have patches that apply the already clear parts of the coding standard, you can attach them to Ticket #11971. Feel free to suggest your own issues into the comments on the coding standard post. I therefore closed comments here.

This entry was posted in Pressed and tagged , , , , , , , . Bookmark the permalink.