search

graze / standards

⚖ The coding standards of the graze tech team.
https://graze.github.io/standards/
MIT License
6 stars 2 forks source link

New section for DocBlock + a couple of new standards #21

Closed mathieupinet closed 8 years ago

mathieupinet commented 8 years ago

New standards:

mathieupinet commented 8 years ago

will pill says:

would be good to clarify what we must/should do for return types that are arrays of arrays or arrays of mixed types also, can return Type[] return an empty array?

wpillar commented 8 years ago

Fine with me. Should share it around to get feedback from others.

Would also be good to adapt our code sniffer standard to pickup this stuff as much as possible: https://github.com/graze/graze-standards/blob/master/PHP/CodeSniffer/Graze/ruleset.xml

Writing custom sniffs is pretty easy.

sjparkinson commented 8 years ago

Needs some links to what tags are actually valid (how about this?), and what are required on a method.

I'd assume param, returns, throws, what else?

What about {@inheritDoc} usage?

I'd say we should recommend having a distinction between a short and long description on a method, kinda like git.

What about the formatting of the (long) description? I'm cool with markdown, but maybe tools better support html.

mathieupinet commented 8 years ago

@sjparkinson @return and @param are the only required ones, isn't it clear from https://github.com/graze/standards/pull/21/files#diff-04c6e90faac2675aa89e2176d2eec7d8R66 ?

mathieupinet commented 8 years ago

@sjparkinson thinking about @inheritdoc (and learning that it only really inherits the description) led me to this thought: should classes that inherit the exact same documentation even HAVE a DocBlock?

wpillar commented 8 years ago

I've been thinking about @inheritdoc and I'm currently thinking that we shouldn't use it and we should explicitly define the doc block for sub-methods.

mathieupinet commented 8 years ago

@sjparkinson I haven't come across methods with a description verbose enough that I had to consider a special format for it. Is it an issue in our Open Source projects?

sjparkinson commented 8 years ago

@sjparkinson @return and @param are the only required ones, isn't it clear from https://github.com/graze/standards/pull/21/files#diff-04c6e90faac2675aa89e2176d2eec7d8R66 ?

Yes, after re-reading it. Being totally honest I found a lot of these verbose and just skimmed them.

@sjparkinson thinking about @inheritdoc (and learning that it only really inherits the description) led me to this thought: should classes that inherit the exact same documentation even HAVE a DocBlock?

Yes, return values can change, and I've never seen otherwise elsewhere.

@sjparkinson I haven't come across methods with a description verbose enough that I had to consider a special format for it. Is it an issue in our Open Source projects?

Something to consider another time.

mathieupinet commented 8 years ago

@sjparkinson @wpillar : just realised this was still unmerged, are there pending issues?

mathieupinet commented 8 years ago

Closed to create a new PR as #25.