Review main Abandoned

11344[TASK] Remove @author function annotations in /typo3/sysext/

Wouter Wolters CR 0 V 0 Normal +56 −69 updated 06/03/13, 20:49

Commit message

Remove all @author annotations from the function doc comments.

Review

  • Code review CR 0
  • Verified V 0

Issues 1

Files 14

Review log 26

Show 1 earlier messages
  1. Tolleiv Nietsch commented on patch set 1 05/29/12, 09:35

    Verified; Looks good to me, but someone else must approve
  1. Dmitry Dulepov commented on patch set 1 05/29/12, 09:35

    Do not submit
  2. Oliver Klee commented on patch set 1 05/29/12, 09:35

    I'll rework the patch accordingly.
  3. Oliver Klee commented on patch set 2 05/29/12, 09:35

    Looks good to me, but someone else must approve
  4. Oliver Klee uploaded patch set 2 05/29/12, 09:35

  5. Philipp Gampe commented on patch set 1 05/29/12, 09:35

    Verified; Looks good to me, but someone else must approve Patch applies, only changes in comments thus no further testing.

    class.tslib_content.php:38

    space instead of tab please, also next line
  6. Philipp Gampe commented on patch set 1 05/29/12, 09:35

    I would prefer that you didn't submit this Actually I agree with Oli here.
  7. Philipp Gampe commented on patch set 2 05/29/12, 09:35

    (1 inline comment)
  8. Ingo Renner commented on patch set 3 05/29/12, 09:35

    Do not submit see the comments in forge...
  9. Ingo Renner commented on patch set 3 05/29/12, 09:35

    There are some simply wrong changes, also concerning my contributions. But it's more that I oppose the change in general, like other devs here... Just stop wasting time with (re)moving contributor acknowledgments, please.
  10. Oliver Klee commented on patch set 3 05/29/12, 09:35

    Jigal, thanks for your explanations. What do you propose? (I assume that we're aiming to get as much from the CGL as possible into CodeSniffer rules at some time.) a) change the CGL, clarifying the exceptions b) leave the @author function annotations and not add this to the CodeSniffer rules c) leave the @author function annotations and add exceptions (which?) to the CodeSniffer rules And if you don't want to spend your time on these changes (which is okay), could you please remove your blocking votes to other people who care about these kind of changes can continue working on these two change sets?
  11. Oliver Klee commented on patch set 3 05/29/12, 09:35

    Looks good to me, but someone else must approve
  12. Jigal van Hemert commented on patch set 3 05/29/12, 09:35

    The quote says "should not" and not "must not" or "may not". So, it's not a big issue. The harm: take for example fe_login. Steffen has written most of the code, Bernard contributed a specific function. For me this is valuable information: if I have questions about that function I could ask Bernard (if he would still be in the community), for the rest I could ask Steffen (if he....). How many hours have already been wasted on these annotations? All this time could've been spent on real bugs or features. CGL are not the holy grail, they are helpful to make code readable and PhpDoc comments help in IDEs and documentation. Okay, enough of my time wasted on this :-(
  13. Jigal van Hemert commented on patch set 3 05/29/12, 09:35

    @Philipp: I already explained the arguments in one of the issues on the forge discussion, but I'll repeat it here in different wordings. 1. the CGL does not forbid @author annotations at function level. It says it SHOULD not be used. An example from RFC2822: "Each line of characters MUST be no more than 998 characters, and SHOULD be no more than 78 characters, excluding the CRLF." This means that lines of 231 characters are allowed, but not encouraged. A validator / mail client must accept such a line and not complain about it. The same is true for the code sniffer with @author annotations. 2. the current use of @author gives in most cases detailed information about the contributions. Examples: * if two people write a class together it's logical to add them both as author of the class * if someone adds a specialistic function or a function is used from a third party (with the right license) it is logical to just use that author for the single function * if someone refactors a class it's logical to add him/her as author to the entire class Some examples of the touched classes: - tx_felogin_pi1 : Steffen wrote the class, Bernard contributed the generatePassword() function. This is not enough for me to add him as author of the class. If that change was pushed now we might not have added him as author of the function, but it isn't nice to remove his authorship either. - tslib_cObj : the function removeBadHTML() was added from a third party (Thomas Bley). He did not contribute it himself. It doesn't feel right to add him as author of the entire class. Also the reference to the origin and the license is now removed. It was mentioned that the purpose of the @author annotation in a class was to give credit and to indicate whom to contact. By moving the authors from single functions to the class incorrect information is given for both purposes. In the two examples above: Thomas does not know anything about the class (or the entire TYPO3 project) and should not be credited for the entire class. Bernard may know a bit about the class, but to credit him for making fe_login is a bit too much. On the other hand for the specific function he contributed he might know more about some details than Steffen who originally made the class. (I ignore the fact that authors might not be in the current community any more for this argumentation) 3. the CGL are not a constitution. They are meant to make code more readable and give it more consistent look. CGL "violations" (another heavy word) are not enough to give negative votes to a patch IMO; they can easily be fixed by pushing a new patch just prior to merging. In pre-git/gerrit days patches were committed with CGL changes added by the committer. NOTE: I couldn't find any "strong" arguments for having this change, other than the single line in the CGL and a desire to change this into a must-rule in a code sniffer. NOTE2: The whole CGL craziness will give us a code sniffer which will complain about tabs and spaces, but will happily accept functional code problems (SQL injections, non-strict comparison in in_array(), etc.).
  14. Jigal van Hemert commented on patch set 3 05/29/12, 09:35

    Do not submit Patch does more harm than good and has no functional benefit.
  15. Jigal van Hemert commented on patch set 3 05/29/12, 09:35

    > What do you propose? I propose to spend time on real issues which actually improve the functionality of TYPO3. > a) change the CGL, clarifying the exceptions The CGL says "SHOULD". In most internet standards there are three levels: MUST, SHOULD and MAY. In this case a SHOULD means that you cannot make a rule in the CodeSniffer. > And if you don't want to spend your time on these changes (which is okay), > could you please remove your blocking votes to other people who care about these kind of > changes can continue working on these two change sets? Why must every proposed change be merged in the end? There are already two votes against it. Doesn't that mean something?
  16. Philipp Gampe uploaded patch set 3 05/29/12, 09:35

  17. Philipp Gampe commented on patch set 3 05/29/12, 09:35

    Verified; Looks good to me, but someone else must approve I just fixed the issue I mentioned in the comment. Turned out be a the actual character and not a tab. Anyway should not have been there.
  18. Philipp Gampe commented on patch set 3 05/29/12, 09:35

    So whats the harm? <quote>Note that the @author tag should not be used in function or method phpDoc comment blocks – only at class level – because it is too liable to change frequently and authors would accumulate indefinitely. git blame is enough for tracking changes. </quote> http://typo3.org/documentation/document-library/core-documentation/doc_core_cgl/4.5.1/view/1/3/#id1007051
  19. Philipp Gampe commented on patch set 3 05/29/12, 09:35

    @Jigal If you don't want to spend time on this, then please don't. Not many people spend time on CGL cleanups os place lets those who does do what the want to do. If you have "hard" arguments, please write them down - here or on forge. By all what I know about giving -2 votes, just "I don't like this" does not justify a block.
  20. Mr. Jenkins commented on patch set 1 05/29/12, 09:35

  21. Mr. Jenkins commented on patch set 2 05/29/12, 09:35

  22. Mr. Jenkins commented on patch set 3 05/29/12, 09:35

  23. Wouter Wolters commented on patch set 1 05/29/12, 09:35

    For discussion, first see http://forge.typo3.org/issues/37339
  24. Wouter Wolters commented on patch set 3 05/29/12, 09:35

    @Ingo can you explain which comments? The comments in Forge has been fixed already in this patch. Except the one from Jigal
  25. Wouter Wolters commented on patch set 3 05/29/12, 09:35

    Abandoned