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.

SitFRA - No Comment?


Published on

A presentation about the art of commenting your code for SAP Inside Track Frankfurt, 10 March 2018.

Published in: Software
  • Unlock The Universe & Get Answers You Seek Today In Your FREE Tarot Reading. DO THIS FIRST... To get the most out of your tarot reading, I first need you to focus your intention - this concentrates the energy on the universe to answer the questions that you most desire the answers for. Take 10 seconds to think of your #1 single biggest CHALLENGE right now. (Yes, stop for 10 seconds, close your eyes, and focus your energy on ONE key problem) Ready? Okay, let's proceed. ➢➢➢
    Are you sure you want to  Yes  No
    Your message goes here

SitFRA - No Comment?

  1. 1. No comment? sitFRA | 10 March 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? @laurensvanrijn
  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 ―Comments that warn you about consequences ―Comments in English ―Comments for ABAP Doc ―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 ― ― ― ― ― pment.pdf ― ―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