Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

sitHH - No comment?

110 views

Published on

A revised presentation about the art of commenting your code for SAP Inside Track Hamburg, 9 June 2018.

Published in: Software
  • Be the first to comment

  • Be the first to like this

sitHH - No comment?

  1. 1. No comment? sitHH | 9 June 2018 | Laurens van Rijn SAP Inside Track presentation
  2. 2. Index Today’s topics: ―About me ―Technical Debt ―Clean Code ―The Art of Commenting ―Code Formatting ―ABAP Doc ―Want to know more? ―Q&A No comment?
  3. 3. About me Working as a software engineer: Uniface (1994-1998), Oracle (1998-2001), JDEdwards (2001-2005), SAP (2005-∞) Interested in code quality: ―2005 Anything goes ―2008 Performance matters ―2013 Code Inspector ―2014 ABAP Test Cockpit ―2015 QA set-up responsible ―2018 Clean Code Evangelist…  No comment?
  4. 4. Technical Debt "The problem with quick and dirty is that dirty remains long after quick has been forgotten." ―Definition: Technical debt is a concept in software development that reflects the implied cost of additional rework caused by choosing an easy solution now instead of using a better approach that would take longer. ―Causes: Lack of documentation, knowledge, collaboration, insufficient up-front definition, last minute spec changes, future- coding etc. ―Risks: difficulty to estimate changes, stressed out developers, (leading to staff turnover), aversion to change. No comment?
  5. 5. Clean Code The principles of clean code: ―Easily accessible to others (straightforward, clear intent, good abstractions, no surprises, good names) ―Is made for the real world, i.e. has a clear error-handling strategy ―The author clearly cares for the software and other developers (which implies both readability and maintainability) ―Is minimal (does one thing, has minimal dependencies) ―Is good at what it does ―Uses as little comments as possible, as many comments as needed. (Comments should tell you why, not what or how. If it can’t be clarified by reading the code, comments may be needed) No comment?
  6. 6. The Art of Commenting (1/5) Spotted on Twitter…  ―"Documentation is a love letter that you write to your future self." - Damian Conway ―A love letter, or an apology? ―Template for copy-paste // Dear future me, // Please don't hate me for this: but.... // *reasoning* // It might not seem that way but I love you. // Sincerely, your past you No comment?
  7. 7. The Art of Commenting (2/5) Good types of comments ―Comments that explain what is happening ―Comments that clarify something that is not legible by regular humans, something that is clear and legible to you is not necessarily clear to others ―Comments to temporarily provide a design blueprint while you are writing the code / To do reminders ―Comments that warn you about consequences ―Comments in English ―Comments for ABAP Doc / abapCI plugin ―Unit tests (alternative comments) No comment?
  8. 8. The Art of Commenting (3/5) Bad types of comments ―Journal comments ―Superfluous comments: They just state what is written below, but differently ―Obsolete comments: • Comments form part of your code and should be maintained as well • Most pseudo comments • Commented code that should have been removed No comment?
  9. 9. The Art of Commenting (4/5) Bad types of comments ―Comments that should have been better variable or method names ―Comments that are necessary because no time was spent to write clear code (e.g. closing bracket comments) ―Comments created to fulfil Code Inspector requirements AKA fluff comments ―Global comments in a local place No comment?
  10. 10. The Art of Commenting (5/5) Bad types of comments ―“Funny” or unprofessional comments No comment?
  11. 11. Code Formatting Your code as art? ―"The visual and intellectual enjoyment of well-formatted code is a pleasure that few non-programmers can appreciate. But programmers who take pride in their work derive great artistic satisfaction from polishing the visual structure of their code.“ ―Pretty Printer set-up ―Know the difference: “ vs. * ―Blank lines usage ―Grouping & ordering ―Indentation & alignment ―Be a Boy Scout… No comment?
  12. 12. ABAP Doc (1/2) Generates the documentation for your coding ―“! Indicates comments for ABAP Doc ―Part of Eclipse only ―Reduces documentation effort ―Synchronizes with SE24 / SE37 short texts (NW 7.5 or higher) ―Export as HTML pages (NW 7.5 or higher) ―Supported by Code Inspector No comment?
  13. 13. ABAP Doc (2/2) No comment?
  14. 14. Want to know more? Literature ―https://www.agilealliance.org/introduction-to-the-technical-debt-concept/ ―https://en.wikipedia.org/wiki/Technical_debt ―https://blogs.sap.com/2013/04/29/abap-doc/ ―https://www.sebastiansylvan.com/post/the-perils-of-future-coding/ ―https://www.dsag.de/sites/default/files/dsag_recommendation_abap_develo pment.pdf ―https://jason.pureconcepts.net/2015/01/are-you-a-boy-scout/ ―Books by Robert C. Martin: • Clean Code: A Handbook of Agile Software Craftsmanship • The Clean Coder: A Code of Conduct for Professional Programmers No comment?
  15. 15. Say hello to questions & answers

×