The document provides an overview of topics related to code quality, including technical debt, clean code principles, best practices for commenting code, code formatting, and using ABAP Doc to generate documentation. It was presented by Laurens van Rijn, who has worked as a software engineer for various companies since 1994 and now focuses on code quality as a Clean Code Evangelist. Technical debt is defined as additional work caused by taking easy solutions now instead of better approaches later. Clean code principles include readability, minimalism, and using comments only where needed to explain why rather than what or how. Good and bad types of comments are outlined. Formatting code like art and using Pretty Printer, blank lines, grouping, and indentation properly
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. 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 / 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. 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?
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.
abapCI is an additional free plugin for ABAP in Eclipse which supports you with Continuous Integration features.
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/
