Let us spend less time writing trivial stuff and more time focusing on great code that doesn't need documentation to be understood.
Save other peoples time by writing less !
2. Aboutme Volker Dusch / @__edorian Doing PHP for ~7 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 !
3. Aboutyou You seem to be smarty people I guess you are motivated And I'm just going to assume you work with smart people you respect
4. This is about time About your time About my time About the next guys time
5. So stop wasting time Take more time writing code, you are only doing it once Make everyone waste less time reading code, that happens quite a lot Disclaimer: When saying ‘documentation‘ inever talk about @phpdoc for apis (@param, @return)
6. Oh yeah by that way I won’t be talking about ’design’ very much Bad design hurts… but you’ll get over it … or at least used to it Bad code hurts every day because it sucks differently every time
7. Samples are next Stuff I’d say you all know about: SCM Unit testing Dependency Injection That Singletons / Statics / Globals are evil Other design mumbo jumbo
8. Yay ! Samples class myClass { /** * Constructor */ public function __construct() { } // methods... }
9. Yay ! Samples class myClass { /** * Create an instance of ‘myClass’ */ public function __construct() { } // methods... }
10. Yay ! Samples class myClass { /** * @return myClass */ public function __construct() { } // methods... }
11. Yay ! Samples class myClass { public function __construct() { } // methods... }
13. So… But everything has to have a docblock ! It‘s in the guidelines ! But i might need it later ! That's just because it‘s in the template and i didn‘t delete it
14. DOCUMENT EVERYTHING !!1 That's at least what they told me Provocation incoming: Good code is hard document Bad code is easy to document
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) {…}
16. ‘Good‘ Code class user { public function getUserId() {…} public function getFirst/Last/DisplayName() {…} /** @link … */ public function getBodyMassIndex() {…} /** @param float $kilogramm */ public function setWeight($kilogramm) {…}
17. Again A short, undescriptive, function name like ‘calc‘ always make it easy to write documentation Sadly people will need to read it (again and again ..)
23. 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
24. Inline Sample public function generateReport() { // get the db connection $reg = GlobalStorage::get(“db“); // auth if(!$reg->getOne(“SELECT VIEW_REPORT FROM USER ….“)) {…} $id = $reg->getOne(“select … „); // template // render new ReportTemplate($id); // ….
25. Inline Sample public function generateReport() { $this->checkAuthentication(); $template = this->createReportTemplate(); $this->renderReport($template); } That's not perfect but the ‘// next block‘ comments are gone
26. 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 USEFULL comment. Know who you write docs for
27. 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
28. 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.