Recommended
More Related Content
What's hot
What's hot (20)
Similar to SitFRA - No Comment?
Similar to SitFRA - No Comment? (20)
Recently uploaded
Recently uploaded (20)
SitFRA - No Comment?
- 1. No comment? sitFRA | 10 March 2018 | Laurens van Rijn SAP Inside Track presentation
- 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. 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. 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. 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. 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. 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. 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. 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. The Art of Commenting (5/5) Bad types of comments ―“Funny” or unprofessional comments No comment?
- 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. 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?
- 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. Say hello to questions & answers
Editor's Notes
- This is one of the great discussions among developers: document or not document your code? Is it worth writing documentation in your code? I thought this topic was completely overcome and it was clear that, except some few occasions (implementing a public API), documentation was not necessary. Until I saw a code review where the reviewer pointed out the lack of documentation as an issue. Really? I was one of those who used to document my code… or at least I tried. I was so convinced that code had to be documented. As a backup or reminder for my future myself or any other developer lucky enough to end up in my code. Although I always realized it was always out of date. And by then, I already wondered: what is the purpose of documenting the code if the documentation is always outdated? Until several years ago I read the book Clean Code. I saw it "crystal clear", there is no need to document your code if you code your documentation. With this I mean to use meaningful variable and method names. If the name of the member already tells you the information that it is keeping and the name of the method tells you what the method is doing you can end up reading the code without the need to figure out or document what your code is doing. Extract as much code as you can to methods. Even if you end up having a method with only 3 or 4 lines. Each method should do one thing and only one thing. And the name must explain what it does. Each member of a class must have a name that only reading it you know which information you can find there. Same for variables and input parameters. Following this simple steps you can have a code you can read, having the documentation right in the same code. Yes, I know, there are those times you have to implement code with a complex algorithm or you are copying a code you found on Internet which might be complex, you might not understand and you might not extract in simple and meaningful methods. Yes, there are always exceptions. What do you think? Do you document or write the documentation in your code? “Comments are not necessary, code should be self-documenting.” “Use as little comments as possible, as many comments as needed.” “Don’t document your code, code your documentation” “Code is like humour. When you have to explain it, it’s bad.” “Write code that minimizes the time it would take someone else to understand it - even if that someone else is you.”
- English should be used for the comments. 1) Today, development work is most often done in international teams and even if you currently do all your development in another language, there is always the likelihood that your project will become more global in nature over time. The later effort will then run into coordination issues, or have to re-engineer translations, and this will be more difficult than the possibly somewhat larger initial effort of writing the docu- mentation in English. 2) It has also been shown, that the readability of the code and comments is improved if the comments are in English. The reason for this is that the ABAP statements are also English-like and have a structure similar to sentences. Anybody reading the English documentation in the code then does not have to keep switching back and forth between different languages. Unit tests also indicate what the code does and so acts like a form of documentation to help you understand the code. + Legal comments Todo comments Informative comments Explanation of intent Clarification Warning of consequences Amplification ABAP Doc
- You really should document your code. “Retrieve material info” for SELECT * FROM mara. Your comments should always be up-to-date. The character string "#EC after a statement or a part of a statement, which is followed by an ID with the prefix "CI_", defines a pseudo comment for Code Inspector. These pseudo comments can be used to hide certain warnings from Code Inspector for the statement in question. The possible IDs are documented in Code Inspector or in the output of its messages. Alternatively, tweak your Code Inspector settings. Report ABAP_SLIN_PRAGMAS will tell you the relevant Pragma Code for each Pseudo Comment. Code Inspector can spot lines of commented code but may not be able to discern English text from code… - Mumbling Redundant Misleading Mandated Journal Noise, restate the obvious Scary noise / copypasta error comments Don’t use a comment when you can use a variable or function Position markers Closing brace comments Attributions and bylines Commented out code HTML comments Non local info Too much lines of info Function header, can replace comments
- Mandatory method signatures or generated code blocks don’t always allow this. It also touches on the discussion whether a Hungarian naming convention should be used. … As you can see you can have a lack or a surplus of comments… Most of us have had the experience of working on spaghetti code. Many of us have produced some spaghetti code ourselves. It’s easy to write code that we understand, because at the time we write it we’re deep in an understanding of the problem we’re trying to solve. Other maintainers of the code aren’t going to have so deep an understanding.
- Choose clarity over entertainment value. A Star Trek reference is not a major problem, the other two are definitely not professional. Please note that “Fuck” will give you the same results as “Fuck you sap” (separate words).
- “Try and leave this world a little better than you found it, and when your turn comes to die, you can die happy in feeling that at any rate, you have not wasted your time but have done your best.” - Robert Baden-Powell, founder of the Boy Scouts. When applied to ABAP development, this means, eliminating dead code (unused variables, unreachable code), removing comments, and standardizing format. No changes, the functionality does not change. * = Full-line comments / “ = Inline comments (Pretty Printer says )
- Checking ABAP Comments for Completeness via Code Inspector The ABAP comments are checked for completeness. In other words, the system checks if there is a comment for all the entities activated via the parameters. Nog uitschrijven… https://blogs.sap.com/2013/04/29/abap-doc/ https://blogs.sap.com/2015/10/21/new-abap-doc-features-with-netweaver-75/