Help Us To Help You – Share Your Code
Yesterday I tweeted: “We should encourage folk to post full Gists with their ui5 issues, for easier debugging and analysis ( )”
So I decided to put my money where my mouth is and write this document.
Background and Context
There are many examples in the SCN SAPUI5 Developer Center where people are posting questions asking for help with code, and where they don’t supply enough information, background, context, or — crucially — code. If you have a problem with your code and want help from other people, help us to help you by sharing the code you’re having problems with.
There are good ways and bad ways to share code. Here are a few tips:
Share all of the code
Unless you’re asking questions about, for example, specific syntax or code patterns, don’t just post code snippets, and make us guess the rest. Post all of your code. Even the parts that you might not think are relevant. If you’re experiencing problems, and don’t post all of the code, you’re second-guessing the cause, and not helping yourself or us. Remember, we haven’t been working on your codebase and so don’t have the mental context that you have.
If you can’t share all of your code for some reason (intellectual property, security, whatever) then reduce the problem to its core essence and post that – but again, post a complete example. Often, going through the exercise of reproducing the problem in the smallest instance possible leads you to realise what the problem is, and you may not need to ask for help. But if you do, you have at least something to show the people who can help.
Share the code in a useful way
Posting large (or even small) chunks of code inside the body of a forum question here on SCN is not that helpful. The syntax highlighting, formatting and font choice that this environment offers as default is not conducive to reading code. Further, posting your code like that makes it that much more difficult for your helpers to marshal it into something that they could run locally to see if they could diagnose the problem themselves. The one exception is where you’re providing an initial bit of context. And if you do that, make sure you use the syntax highlighting provided by the SCN Jive editor. It’s not brilliant, but it’s better than nothing.
ZIP files of complete applications are better, but they’re still very cumbersome – you have to download them in your browser, unzip the files, choose a directory, and so on. And nobody can read the code at their leisure, or get a quick understanding of what’s going on.
Use Github’s Gists
Best of all, at least IMHO, is to create a Gist on Github. This puts the code centre stage, treats it as a first class citizen on the Web (you can address whole applications, individual files, or even individual lines, with their own URLs) and what’s more, it’s one command to pull the entire codebase of an application to a local directory and start working on it immediately. If nothing else, sharing the code you want help with as a Gist on Github puts the onus on you, who are seeking help (rather than your potential helpers, who are offering help) to marshal the code so that it can be properly diagnosed.
Here’s a recent of example of where someone had a problem with his application and asked for help, posting not only a formatted snippet to provide initial context, but also a Gist with a complete working runnable example that highlighted the problem he was having.
Uwe did exactly the right thing. The Gist he created and shared – “Binding Problem with UI5 and XML views” was complete, didn’t omit anything, and was runnable. It took me less than a minute to grab the code and get it running and confirm what the issue was. This particular problem wasn’t a big issue, but there are more complex problems that are presented in this area on SCN that are very difficult to diagnose because not only is the code not shared, nor a complete description of the issue given, but also the problem is complex in that it involves relationships between different components and files … which are often missing.
With a Gist, not only can the whole application be downloaded quickly and easily, but also you can review the code in properly formatted and syntax-highlighted fashion, and even point to certain lines (like the last line of the bootstrap, which was missing the data-sap-ui-xx-bindingSyntax setting)
Here’s a short screencast of how that shared code, in a Gist, is very easy to pull down locally, fire up and start to diagnose.
Hat tip to my son Joseph Adams, who first showed me that Gists could contain more than one file, and for pointing out that they were normal git repos.
Nice to see how share-friendly the SAP developer community is becoming!
As you probably know, there have been parts of the SAP developer community that have been sharing code for literally decades. And if you look back over the history of SCN you'll see many early articles, documents and posts that share code.
But you're absolutely right, to point out that this trend is increasing by large factors - I think in part this is down to many things, including
If developers are the new kingmakers, then code is the new currency. Or something like that 🙂
Excellent, DJ, thanks a lot!
When you ask for help, you request others to invest effort. Put yourself in their shoes: how likely is it that you would step in and help if you first have to invest lots of time to understand and clarify the problem? If you expect that you have to ask questions back and forth before the issue is sufficently clear that you can probably find the solution?
Making it easy to help you means making it likely that somebody will help you!
Investing some effort to ask the question properly and to make helping easy shows everyone that you are serious about the question and that the answer is really important to you. This will make people more inclined to help you.
Providing a Gist as described above is a perfect way to do this: to make it easy for people to help you.
An alternative, even easier way is using http://jsbin.com/ or a similar code snippet hoster:
the code AND the running app is just one click away for anyone who might help you.
Modifications can be done AND tested in-place without downloading anything, so the solution can be easily found - and then saved and sent back to the person asking the question.
This would be an example UI5 code snippet as starting point:
This approach has two drawbacks: 1.) loading UI5 from a different domain does not work in older IE versions and 2.) you cannot use multiple files - everything must be in one file, so normal UI5 Views, Controllers cannot be used as-is (they can be packed into this one file, though).
So this approach is best suited for problems which can be reduced to a quite small example.
But this isn't necessarily a bad thing: DJ, you mentioned already that reducing the problem might help finding the solution. It also makes it more likely for others to help because it reduces the time they need to analyze the issue. I'd even recommend to always try to reduce the problem as much as possible.
Great comments Andreas, thanks.
Yes, JSBin is another good solution for the reasons that you state. And for those wondering how they might include a complete MVC example in such a single-page environment, you might be interested in this snippet in sublimeui5
SublimeUI5/Snippets/indexmspmvc.html.sublime-snippet at master · qmacro/SublimeUI5 · GitHub
Share & enjoy!
Excellent DJ, Great way to get the questions answered. 🙂
Volume on the Youtube video was too low.
I'll speak up on the next screencast 🙂
Good to see there's a few great options to share and review code. I've found these sources mighty helpful during my UI5 journey. In some situations where I've had to solve the problems by myself it's also a great way to give back and share these insights on these platforms too which I hope we get to see more of over time!