Write less stupid documentation and spent the time writing good code that doesn't need docs.. and some other related stuff

1. Clean code:Stop wasting my time February 17, 2011 1

2. About me Volker Dusch / @__edorian Doing PHP for ~8 years now I’m sorry for the bullet points, I don’t know any better(There will be code, and cake, maybe) Feel free to interrupt me at any time! February 17, 2011 2

3. About you You seem to be smart people I guess you are motivated And I’m just going to assume that you work with smart people you respect February 17, 2011 3

4. This talk is about time About your time About my time About the next guys time February 17, 2011 4

5. So stop wasting time Don’t make me spend time trying to figure out what you are doing Don’t spend your own time writing stuff that isn’t going to help me anyways A little disclaimer: When I talk about ‘documentation’ I don’t mean @phpdoc tags for api docs (@param & @return) February 17, 2011 5

6. What I would talk about Good documentation means less documentation How does that work for your team Commit messages I LIKE to read Everything related you want to discussIf we don’t make it through the slides I’m happy February 17, 2011 6

7. Stuff you all know about SCM Unit testing Dependency Injection Why we don’t like singletons / static functions and other globals Other design mumbo jumbo If not: Read up on it. There are great resources out there February 17, 2011 7

8. Yay! Samples class myClass { /** * Constructor */ public function __construct() { } // methods... } February 17, 2011 8

9. Yay! Samples class myClass { /** * Create an instance of ‘myClass’ */ public function __construct() { } // methods... } February 17, 2011 9

10. Yay! Samples class myClass { /** * @returnmyClass */ public function __construct() { } // methods... } February 17, 2011 10

11. Yay! Samples class myClass{ public function __construct() { } // methods... } February 17, 2011 11

12. Yay! Samples class myClass{ // methods... } February 17, 2011 12

13. So… Seems mundane? That stuff scales! But everything needs to have a docblock! But I might need it later That‘s just because it‘s in the template and I didn‘t delete it February 17, 2011 13

14. DOCUMENT EVERYTHING !!1eleven February 17, 2011 14 At least that’s what they told me How about that: Good code is hard to document Bad code is easy to document I prefer good code over a lot of docs

15. Bad code class User { public function getId() {…} public function getName() {…} /** Calculate Body-Mass-Index @link … */ public function getBMI() {…} /** @param float $kg Weight in Kilogramm */ public function setWeight($weightInKg) {…} February 17, 2011 15

16. Bettercode class user { public function getUserId() {…} public function getFirst/Last/DisplayName() {…} /** @link … */ public function getBodyMassIndex() {…} /** @param float $kilogramm */ public function setWeight($kilogramm) {…} February 17, 2011 16

17. Again Short and undescriptive function names make it very easy to write documentation Good ones make it hard to write meaningful stuff Sadly people will need to read your docs again and again and again February 17, 2011 17

19. Consistency ?

21. Output – It‘s like autoloading <?php /** * @package module_x * @subpackage y_z */ /** * @package module_x * @subpackage y_z * @since creation_date * @version 1.2.3.4 */ class myClass { } February 17, 2011 20

22. Know your user or coworker February 17, 2011 21

23. This is phpdoc &phpcs valid Well… after the build script <?php class myClass { } *You might need 2 phpcs standards? February 17, 2011 22

24. A final test See if you can spot the issues Or just guess what I‘d complain about February 17, 2011 23

25. February 17, 2011 24 abstract class xyzRequest { /** * Initializes this xyzRequest. * * Available options: * * * logging: Whether to enable logging or not (false by default) * * @param xyzEventDispatcher $dispatcher An xyzEventDispatcher instance * @param array $parameters An associative array of initialization parameters * @param array $attributes An associative array of initialization attributes * @param array $options An associative array of options * * @return bool true, if initialization completes successfully, otherwise false * * @throws <b>xyzInitializationException</b> If an error occurs while initializing this xyzRequest */ public function initialize(xyzEventDispatcher $dispatcher, $parameters = array(), $attributes = array(), $options = array()) {

26. Another one? /** * Retrieves the uniform resource identifier for the current web request. * * @return string Unified resource identifier */ publicfunctiongetUri() /** * See if the client is using absolute uri * * @return boolean true, if is absolute uri otherwise false */ publicfunctionisAbsUri() February 17, 2011 25

27. Inline Comments $i++ // Increment $i by one Yeah.. we don‘t need to talk about that Can be great, especially when they tell you ‘WHY‘ something was done Most time aren‘t that great February 17, 2011 26

28. Inline Sample public function generateReport() { // get the db connection $reg = GlobalStorage::get(“db“); // auth if(!$reg->getOne(“SELECT view_report FROM USER ….“)) {…} // template $id = $reg->getOne(“select … „); // render new ReportTemplate($id); // …. February 17, 2011 27

29. Inline Sample public function generateReport() { $this->checkAuthentication(); $template = this->createReportTemplate(); $this->renderReport($template); } That's not perfect but the ‘// next block‘ comments are gone February 17, 2011 28

30. No docs are not the answer I‘m not saying BE GONE all documentation Let‘s remove useless comments ! Let‘s (maybe ?) agree upon that sometimes there is no USEFUL comment. Know who you write docs for February 17, 2011 29

31. It‘s not ONLY about the code Commit messages matter ! Commit message are like book covers, they raise expectations. The diff should tell a matching story Don’t repeat the obvious, tell why you did it and then show me how in the diff February 17, 2011 30

32. Commits Yes, this highly depends on your team Fixes #5232 Fixes #4523 with the last release the database structure changed Reworked the Authentication to account for the new SingleSignOn Fixed some problems Tidy | phpdoc | cleanup | etc. February 17, 2011 31

33. Git made this worse More smaller commits tend to make people just describe what they do and not why they did it Delete Tweak output Rename variable Add cacheTokensattribute Moved code from A to B February 17, 2011 32

34. To sum up Don’t write documentation you think has no use See if you can substitute documentation with more descriptive naming Always: Do what your team has agreed upon and if you don’t like it try to change it if there is a benefit others see too. February 17, 2011 33

35. Comments?Questions! Anything else? 34 Volker Dusch @__edorian

36. Thank your for your time Tell me if you liked it. And tell me if not!) Volker Dusch @__edorian 35