I often share ABAP code via forums, github and so on, which is often intended to work on any ABAP-based system. Unfortunately, it often happens that some of the objects I use (database tables, types and so on) only exist in the solution I am working with (for instance C/4HANA which works on an ABAP system).
It's important to understand that there are several solutions developed by SAP, which are independent from other solutions, but are to be installed on an ABAP system, which includes the ABAP language itself and closely-linked external objects like those in the ABAP dictionary. Such SAP solutions are SAP R/3, SAP CRM, SAP SRM, SAP SCM, SAP BW, S/4HANA, C/4HANA, BW/4HANA, SAP Solution Manager, etc.
For instance, let's say I want to ask a question about the join in ABAP and I provide the following example (that I developed on a C/4HANA system, but the question doesn't concern C/4HANA):
REPORT.
DATA gt_partner TYPE TABLE OF crmd_order_index-partner_no.
SELECT DISTINCT a~partner_no
INTO TABLE gt_partner
FROM crmd_order_index AS a INNER JOIN crm_jest AS b
ON a~header = b~objnr
UP TO 10 ROWS.
cl_demo_output=>write( crmd_order_index ).
Many people have S/4HANA, not C/4HANA, so the code won't compile on their system because the database table crmd_order_index exists only in C/4HANA. Probably those people won't answer or they won't be able to verify their answer, so I think I could make an effort to improve the example and make it work on any ABAP system. This is of course a very simple example, but imagine that you have tens or hundreds of lines.
I know that one solution is to install an ABAP Developer Edition on our own laptop, because it contains the minimal ABAP configuration, and test the ABAP code on it. But it's relatively complex and long to install, occupies a lot of disk space, just to check a "simple thing".
Is there another way to check easily and quickly whether the ABAP code compiles in any ABAP-based system? Or any other idea?
I would also like that this solution applies to code as big as abapGit for instance.
For information:
One well-known ABAP tool which works in any ABAP-based system is abapGit.
The question is not about the versions (for instance for checking that ABAP code made on an ABAP 7.52 system compiles on ABAP 7.0 systems) because I think it's a much more complex problem.
In StackOverflow, an ABAP question whose code doesn't work on any ABAP system weakens the principle of Minimal, Reproducible Examples.
The cleanest way to share a piece of ABAP sample code seems to be this:
create a local package such as $MY_SAMPLE,
copy all sample code and dependencies in,
push it to a new, clean https://www.github.com repository with abapGit, and
add a README that provides the ABAP version the code was written for.
With these best practices:
Reduce the code and dependencies to the minimum required to make the sample work. Remove calls to other development objects not directly related to the problem. Restrict yourself as much as possible to the functions and APIs available from the ABAP platform.
If there are dependencies that form part of the problem, for example in "How do I use the CRM function module XYZ?", or that cannot be copied for size or copyright(!) reasons, identify the SAP software component they are a part of, and list it as dependency in the README.
Verify that the example compiles and works by executing it. This is not reliable, as it may accidentally still access un-copied dependencies you forgot to copy, but it will at least give you an idea.
ABAP is not really special here. Providing minimal working examples is always an effort, in any development language. It requires disentangling the affected code from unnecessary dependencies, and replacing the required ones with minimal working stubs. This is part of why asking good questions is hard work, and why StackOverflow appreciates good questions with reputation.
Sandra I dont think there is a good nor easy answer to this problem. We have been suffering for years with this problem. I got burnt so often with ABAP language across releases. Especially SQL and ABAP unit Tests. Even good old char02 burnt us last week. Yeah Char02 is an industry specific data element no longer supported in s/4 Hana. You need to have every possible release of sap abap be sure all is ok. There is a remote syntax check option, which sounded good at first. However it starts with 7.02 SP14 . So its no good for 7.0 And you need access to these releases in the first place. Who can afford that? Why cant 1 ABAP system be able to do downward compatible checks. :( No Big surprise to me ABAPGit has settled on a recent but not latest abap version as "current version". We have to support code for 7.0 to 7.5+ since we have customers from S/4 hana to 7.0 with 1 code base. We also have a common code base with a SolMan/ CRM and SAP gateway and ECC Business suite. Keeping that code base clean for all environments is easier said than done.
As far as examples go Sticking to strictly ABAP NW examples sounds easy, but unless you limit yourself SFLIGHT or tables like T002 / T006 it is harder than people realize.
A basic but not perfect solution is to check the development class of all objects in a transport before release. We have been doing that for some time. tracking what is a valid Basis object for what purpose is HARD. I have used basis objects that dont exist on 7.2 systems and Failed on import. You can then add a TADIR date to your checks.
At the end of the day I just import into the oldest (7.0) system as a smoke test.
Ill be watching to see if someone has a magic bullet solution :)
Good luck
Since the releases are downwards compatible you can set up a system with a very low release and develop your code on this.
ABAP OO was introduced with release 4.6C
Usually when I'm writing an example, for posting in my blog or somewhere online, I use the travel objects, tables like: sflight, spfli, scarr, etc, which usually are present in most systems, I don't know if they are present in C/4, solution manager or some other solutions, but I think that's probably the best objects to use.
Also another thing that's probably a good idea is to use classic ABAP, and by classic ABAP I mean not using sentences that are only compatible with ABAP >7.40, because in my experience there are still systems on SAP BASIS 7.31.
It's also probably a good idea to use classics reports, unless you are obviously writing about OOPs or the new ABAP 7.40 like sentences.
Your question in not simple as that seems. As you see, the abap code depends on customer repository so you need to have a knowledge of every system to get your code simple and fast.
For the select, you have to know all type of abap possible select.
Best ways is to declare your Types wich contains all of your table so you can select in database without a select distinct. If you have to use a Function or, a class or any kind of object that does not exist on that system, you can create it. Sometimes create is not a best way, so you can search and memorize the oldest functions/calss/object. For example, the function conv_exit_alpha_input you can use now a simple row wich do the same.
So if you want to implement an example abap code, you have to respect the KISS rule and declare as much as you can like readme or creating view or table ect.
Is there something similar to a standard library for modern ABAP (maybe even OO-Abap)? For example a curated list of objects that address some of the most common programming tasks like
high-level data structures (not just plain internal tables)
working with file paths and directories
working with files (reading, saving, ...)
working with different file types (text, csv, xml, ...)
regular expressions
working with the environment (client, application server)
...
My current workflow is to stumble upon a problem like getting the extension of a file from a filename (or something fairly similar and easy). Then I have three options:
Dig through a ton of (mostly old and lacking) posts on SDN until i maybe find a pointer to solve the problem
Hack away and create a one-off solution to the problem
Take my time and implement a good and well documented solution
Many times I feel a bit lost. A lot of the available information is old, bad or both. Is there a more structured approach to tackle the problem of finding a suitable abstraction in the ABAP-world?
To answer your first question no, unlike C, C#, Java, there is no need to include a library since all the functions are always available to you, so in that regards it might be simpler. What you are asking though is a great question, I am sure you probably see tons of queries in SDN for "Is there a Function module for?" etc.
There isn't an easy answer but In SAP ABAP I think the easiest way might be to find this is by looking at packages. Similar to a library by looking at a package for the type of function your looking for might get you there. For example if I am looking for handling files I might look for the control framework package and there I can see all the available functions/classes/methods/BAPIs etc. that are related to front end controls/file handling etc. and might be able to find what I am looking for. Note its not perfect as the way packages are used has changed from time to time so its actually better for finding functions related to for example purchasing or sales etc. but its one way that we use.
Like other languages in that we still need to know what library to link in to get the function you need, in ABAP you just have to find the related package. Hope it helps a little, I know its not perfect. Example package for front end controls
For working with the environment:
If you have access to SAP there is a transaction code called BAPI
Here you could find a hierarchical list of all the main objects in SAP (i.e. Material, Purchase Order, etc)
In this list you could find documentation, the function modules used for the object (i.e. créate/get detail/update etc)
And digging into the function modules could take a look to the structures, receiving parameters, etc
The other questions are a little bit complex, I am not aware of any comprehensive list but digging into SCN usually is easy to find a solution for the most common things like handling files, etc
In the particular case of regular expressions, SAP native language, ABAP, has keywords for handling them, but you also have a class in SAP called CL_JAVA_SCRIPT which you could use for doing thigs in "JavaScript way"
For example I used this class in the past to evaluate a simple formula provided in a string (i.e 3 + 2 * 5 )
This is an operation really complex to do in ABAP but easy to do in JS.
Hope it helps
SAP Reuse Library (SE83) is the most close thing to what you are looking for. It provides common development tasks grouped in hierarchy (UI controls, standard dialogs, confirmation prompts) and contains code snippets for each with commonly used classes/modules:
Though, it is incomplete and lacks many popular things.
Consider also DWDM, BIBS, LIBS transactions and other packages in this link.
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 5 years ago.
Improve this question
I have always liked the documentation on Java APIs, generally speaking, but I know some people consider them lacking. So I'm wondering, what do you consider a good example of API documentation?
Please, include a link or an actual example in any answer. I want to have references that I (and others, of course) can use to improve our own documents.
A good documentation MUST have:
datatypes specs - often more essential than actual functions. Do NOT treat this lightly.
function specs (this is obvious). Including What given function does, why it does it (if not obvious), and caveats if any.
an introduction document that binds the whole into a logical entity, explaining the intentions, correct usage patterns and ideas beyond the scope of actual API code. Normally you are given 50 different functions and you don't know which must be used, which shouldn't be used outside of specific cases, which are recommended to more obscure alternatives and why must they be used that way.
examples. Sometimes they are more important than all the rest
I know how to draw an arbitrary shape of arbitrary color in GTK+. I still have no clue why a change of drawing color requires three quite long lines of very obscure, quite unintuitive lines of code. Remembering SVGAlib's setcolorRGB(r,g,b); draw(x1,y1,x2,y2); I find it really hard to comprehend what possessed the authors of GTK+ to complicate things so much. Maybe if they explained the underlying concepts instead of just documenting functions that use them, I'd understand...
Another example: yesterday I got an answer that allowed me to understand SQLite. I understood a function extracting data from a column returns signed long long. I understood the integer columns could be 1,2,4,6 and 8 bytes long. I understood I can define a column as "UNSIGNED INT8", or "TINYINT". I didn't quite get what "affinity" meant, I just knew both had "INTEGER" affinity. I spent hours seeking whether timestamps should be UNSIGNED INTEGER or INT8, whether INT8 is 8-digits or 8-bytes, and what is the name of that esoteric 6-byte int?
What I missed was that "UNSIGNED INT8", "TINYINT" and the like are all a syntactic sugar synonyms for "INTEGER" type (which is always signed long long), and the lengths given are for internal disk storage only, are adjusted automatically and transparently to fit any value on least number of bits and are totally invisible and inaccessible from the API side.
Actually the iPhone (really Mac Cocoa/framework) documentation has gotten pretty good. The features I like are:
Very easy jump to docs from the API.
Well formatted and the code snippets
you would want to copy and paste
(like method signatures) stand out.
Links to projects with sample code
right from the docs.
Automated document refresh mechanism,
but by default docs are all local to
start (so you can live with a flaky
internet connection).
Easy way to switch between variants
of documentation (to see different
versions of the OS), and also select
which sets of documentation to run
searches against.
An overview section explains what the
class is for, followed by a section
breaking out methods grouped by
purpose (methods to create and
object, methods to query for data,
methods to work with type
conversions, etc), followed by the
detailed method explanations.
I also personally really liked Javadoc and the Java system documentation (I used that for many years), I found a benefit there was it was a little easier to make your own custom docs for your own classes that flowed well with the system docs. XCode lets you also use Doxygen to generate documentation for your own classes, but it would take a but more work to format it as well as the system class docs, in part because the system framework documents have more formatting applied.
A good API will have the following characteristics:
Easy to learn
Easy to use, even without documentation
Hard to misuse
Easy to read and maintain code that uses it
Sufficiently powerful to satisfy requirements
Easy to extend
Appropriate to audience
The most common mistake I see in API design is when developers feel auto-generated XML commenting is sufficient, and then precede to auto-generate their API based off of the XML comments. Here's what I'm talking about:
///<summary>
/// Performs ObscureFunction to ObscureClass using ObscureArgument
///</summary>
void ObscureClass.ObscureFunction(ObscureArgument) { ... }
API's like the one above are only counter-productive and frustrate the developer using the API. Good API documentation should give developers hints as to how to use API and give them insight into certain facets of the API they otherwise would not notice.
I personally believe a perfect example of good documentation is PHP's documentation:
For an example:
http://www.php.net/manual/en/function.fopen.php
I think effective documentation includes:
Parameter listing
(Useful) description of the parameter
If they parameters are a string, list
out and EXPLAIN every possible
possible parameter
Return values on both successful
execution and non-successful
execution
Any exceptions/errors it can raise
Examples (THE MOST IMPORTANT imo)
Optionally:
Changelog
Notes/Examples from other users
Whenever I look up something in the PHP documentation I almost know exactly how to use it without having to scour the internet to find "better" examples. Usually the only time which I need to search the internet is when I need to find how to use a set of functions for a specific purpose. Otherwise, I think the PHP documentation is the greatest example of excellent documentation.
What is think is an example of a alright documentation is Python's:
http://docs.python.org/py3k/library/array.html
It lists out the methods but it doesn't do a good job of actually explaining in depth what it is, and how to use it. Especially when you compare it to the PHP docs.
Here is some really bad documentation: Databinder Dispatch. Dispatch is a Scala library for HTTP that abstracts away the (Java) Apache Commons HTTP library.
It uses a lot of functional-syntax magic which not everyone is going to be very clear on, but provides no clear explanation of it, nor the design decisions behind it. The Scaladocs aren't useful because it isn't a traditional Java-style library. To really understand what is going on, you basically have to read the source code and you have to read a load of blog posts with examples.
The documentation succeeds in making me feel stupid and inferior and it certainly doesn't succeed in helping me do what I need to do. The flipside is most of the documentation I see in the Ruby community - both RDoc and in FAQs/websites/etc. Don't just do the Javadoc - you need to provide more comprehensive documentation.
Answer the question: "how do I do X with Y?" You may know the answer. I don't.
My main criteria is - tell me everything I need to know and everything I'll ever want to know.
QT has pretty decent docs:
http://doc.qt.digia.com/4.5/index.html
Win32 MSDN is also pretty good although it didn't age well.
The java docs are horrible to me. They constantly tell me everything I don't want to know and nothing of what I do want to know. The .NET docs has a similar tendency although the problem there is mostly the extreme wordyness, overflow of so much superfluous details and so much god damn pages. Why can't I see both the summary and the methods of a class in the same page?
I like Twitter's documentation. To me a good API is up to date, easy to read and contains examples.
I think that a good API document needs to clearly explain:
What problem this API solves
When you should use it
When you shouldn't use it
Actual code showing "best practice" usage of the API
Not quite API documentation but nevertheless quite useful is the Oracle database documentation, e.g. for the SELECT statement. I like the inclusion of diagrams which helps to clarify the usage for example.
Just a few thoughts...
Examples - win32 API documentation is better than iPhone's because of:
(short) code examples
I vote for any API doc with small and make-sense examples
Don't ever never show "Form1", "asdf", "testing users" in screen shots or sample codes
good API is solving real world problems and there should be some meaningful examples
Don't auto-gen doc
documentation should not be done during writing code (or by the same guy)
doc is for a stranger, whom the programmers usually don't care of
Avoid ___V2 version of API
but it's not a doc issue
Basically, tell the story of the class at the class level. Why is this here? What should it do? What should be in here? Who wrote it?
Tell the story of methods at the method level. What does this do? No matter how accurate your methods names are, 20-30 characters just won't always cut it for descriptiveness.
#author:
Who wrote this? Who's proud of it? Who should be ashamed of their work?
Interface level documentation tells me:
what should this do?
what will it return?
Implementation level documentation tells me:
how does it do it? what kind of algorithm? what sort of system load?
what conditions might cause a problem? will null input cause an issue? are negative numbers okay?
Class level documentation tells me:
what goes here? what kind of methods should I expect to find?
what does this class represent?
#Deprecated tells me:
why is this planned for removal?
when is it expected to be removed?
what is the suggested replacement?
If something is final:
why didn't you want me to extend this?
If something is static:
remind me in the class level doc, at least implicitly.
In general: you're writing these for the next developer to use if and when you hit the lottery. You don't want to feel guilty about quitting and buying a yacht, so pay a bit of attention to clarity, and don't assume you're writing for yourself.
As the side benefit, when someone asks you to work with the same code two years from now and you've forgotten all about it, you're going to benefit massively from good in-code documentation.
First point for a great API-documentation is a good naming of the API itself. The names of methods and parameters should be say all. If the language in question is statically typed, use enums instead of String- or int-constants as parameters, to select between a limited set of choices. Which options are possible can now be seen in the type of the parameter.
The 'soft-part' of documentation (text, not code) should cover border-cases (what happens if I give null as parameter) and the documentation of the class should contain a usage-example.
Good documentation should have at least the following:
When an argument has additional limitations beyond its type, they need to be fully specified.
Description of the [required] state of an object before calling the method.
Description of the state of an object after calling the method.
Full description of error information provided by the method (return values, possible exceptions). Simply naming them is unacceptable.
Good example: Throws ArgumentOutOfRangeException if index is less than 0 -or- index is greater than or equal to Count.
Bad example: Returns 0 for success or one of the following E_INVALIDARG, etc... (without specifying what makes an argument invalid). This is standard "FU developer" approach taken in the PS3 SDK.
In addition, the following are useful:
Description of the state of an object if an exception is thrown by the method.
Best practices regarding classes and groups of classes (say for exceptions in .NET) in the API.
Example usage.
Based on this:
An example of great documentation is the MSDN library.
To be fair, the online version of this does suffer from difficulty of navigation in cases.
An example of terrible documentation is the PS3 SDK. Learning an API requires extensive testing of method arguments for guessing what may or may not be the actual requirements and behavior of any given method.
IMO examples are the best documentation.
I really like the Qt4 Documentation, it first confronts you only with the essential information you need to get things working, and if you want to dig deeper, it reveals all the gory details in subsections.
What I really love, is the fact that they built the whole documentation into Qt Creator, which provides context sensitive help and short examples whenever you need them.
One thing I've always wanted to see in documentation: A "rationale" paragraph for each function or class. Why is this function there? What was it built for? What does it provide that cannot be achieved in any other way? If the answer is "nothing" (and surprisingly frequently it is), what is it a shorthand for, and why is that thing important enough to have its own function?
This paragraph should be easy to write - if it's not, it's probably a sign of a dubious interface.
I have recently come across this documentation (Lift JSON's library), which seems to be a good example of what many people have asked for: nice overview, good example, use cases, intent, etc.
i like my documentation to have a brief overview at the top, with fully featured examples below, and discussions under these! I'm surprised that few include simple function arguments with their required variable types and default values, especially in php!
I'm afraid i can't really give an example because i havent trawled through to find which ones my favourite, however i know this probably doesn't count because its unofficial but Kohana 3.0's Unofficial Wiki By Kerkness is just brilliant! and the Kohana 2.34 documentation is pretty well laid out too, well at least for me. What do you guys think?
Most people have listed the points making up good API documentation, so I am not going to repeat those (data type specs, examples, etc.). I'm just going to provide an example which I think illustrates how it should be done:
Unity Application Block (Go to the Download section for the CHM)
All the people involved in this project have done a great job of documenting it and how it should be used. Apart from the API reference and detailed method description, there are a lot of articles and samples which give you the big picture, the why and how. The projects with such good documentation are rare, at least the ones I use and know about.
The only criteria for documentation quality is that it speeds up development. If you need to know how something works, you go and read docs. One doc is better than another if you've understood everything from first doc faster than from from second.
Any other qualities are subjective. Styles, cross-references, descriptions… I know people who likes to read books. Book-styled doc (with contents/index/etc.) will be good for him. Another my friend likes to doc everything inside code. When he downloads new library, he gets sources and "reads" them instead of docs.
I, personally, like JavaDocs. Like Apple dev docs with the exception of lower-level parts, for example, Obj-C runtime (reference part) is described awfully. Several website APIs have docs I like also.
Don't like MSDN (it's good in general but there are too many variants of the same document, I get lost often).
Documentation is only a part of the big picture, API design. And one could argue the latter is much more important than just the naming. Think of meaningful non-duplicating method names, etc.
I would definitely recommend watching Josh Bloch's presentation about this:
http://www.infoq.com/presentations/effective-api-design OR http://www.youtube.com/watch?v=aAb7hSCtvGw
This covers not only what you're looking for but much more.
Lots of practical, real-world examples are a must. The recent rewrite of jQuery's API documentation is a good example, as well as Django's legendary docs.
The best documentation I've found is Python. You can use sphinx to generate the source documentation into HTML, LaTeX and others, and also generate docs from source files; the API doc you are looking for.
API docs is not only the quality of the final documentation, but also how easy is for the developers and/or technical writers to actually write it, so pick a tool that make the work easier.
Most things about good documentation have already been mentioned, but I think there is one aspect about the JavaDoc way of API documentation that is lacking: making it easy to distinguish between the usage scenarios of all the different classes and interfaces, especially distinguishing between classes that should be used by a library client and those that should not.
Often, JavaDoc is pretty much all you get and usually there is no package documentation page. One is then confronted with a list of hundreds or even more of classes: where and how to start? What are typical ways of using the library?
It would be good if there were conventions of how to make it easy to provide this information as part of JavaDoc. Then the generated API documentation could allow for different views for different groups of people -- at a minimum two groups: those who implement the library and those who use it.
I find Google APIs a beautiful example of Good documentation API.
They have:
Bird's eyes view of the entire APIs structure
Overviews of the main features of the single API
Nice and colored examples for a quick feedback
Detailed references
A blog that keep you updated
A google groups that documents problems and solutions
Videos
FAQ
Articles
Presentations
Code Playground
A search engine to crawl inside a pile of documentation
That's it!
When I play with google APIs documentation site, I feel at home.
Go to the Doxygen site and look at the examples of the HTML that it generates. Those are good:
http://www.doxygen.nl/results.html