How Google Summer of Code with Open Robotics Changed My Perspective on Software Development
I am proud to announce that I have successfully completed Google Summer of Code 2019 with Open Robotics. For the past three and a half months, I have been writing open-source C++ and Python software for VRX (Virtual RobotX).
VRX is an autonomous boat simulator that uses Gazebo and ROS for physics, rendering, and communication. It is designed to support rapid development, testing, and evaluation of autonomous surface vessels. The software that I wrote adds important features for customization and control, enhances the simulator’s overall realism, and improves the infrastructure for competitions that use the simulator. Read more about the project and my contributions here.
Through this experience, I gained a new perspective on software development. In this article, I will be outlining the key insights I took away from this experience.
Google Summer of Code is a global program that connects open-source organizations with talented student developers. Students spend the summer writing open-source software and connecting with other Google Summer of Code students across the world.
Open Robotics is an open-source organization that builds and maintains robotics software and hardware. They work with industry, academia, and government to support education, research, and product development.
Maritime RobotX is a competition hosted by RoboNation and the Office of Naval Research, in which teams develop an autonomous surface vehicle that will perform various tasks, including navigation, perception, and docking. Teams are comprised of students, faculty, industrial partners, and government partners. Maritime RobotX is RoboNation’s most complex robotic competition to-date.
VRX is a simulation environment designed to support the RobotX Challenge by allowing competitors to test and improve their software extensively on a virtual boat.
Cut the Fat: Give Summaries Before Details
When working on a large open-source project, there is an endless list of things to be done. VRX was no exception. Users were asking for new features to more realistically emulate their physical system, while the VRX team was also focused on improving tutorials for new users, fixing exisiting bugs, and improving the customizability of the boat’s configuration.
The key takeaway is that your team doesn’t have the time to look at every detail of your work; when communicating with your team, always give high level overviews and only dive into the details when it really makes sense to. Whether you’re submitting a pull request, sharing your progress with a coworker, or asking for advice from your supervisor, this rule always holds true.
Giving a high level overview not only gives your audience a better understanding of what you’re working on, but also allows you to gauge their current understanding, which helps you more clearly communicate as you move forward in the discussion.
This is best demonstrated in pull requests. Don’t submit a pull request without a description. Don’t submit a pull request with half a dozen technical questions and no high-level overview. No matter how clean your code is, code alone can never describe what’s not there. You should always include a high level summary of what the PR of trying to accomplish, why you implemented it this way, and simple instructions describing how your reviewers can test the code.
Putting in the extra effort to make your code easier to review will allow your reviewer to give you more meaningful feedback and will improve your development speed.
Here is a good example of a pull request. It has a clear, concise description of what the bug is and includes instructions on how to recreate the bug and test the solution.
Here is a bad example of a pull request. There is no description, yet there are numerous new bash scripts being added to the repository. It is very unclear what is being accomplished and how to test the code additions.
Avoid Analysis Paralysis: Give People Options Not Questions
When approaching a challenging problem, a common issue that software developers face is analysis paralysis: getting so focused on figuring out all of the details that it signficantly slows down development.
It’s easy to get stuck thinking through an endless list of design decisions. Should this script have a default parameter if one is not given? Will this new feature lead to a noticable drop in performance on the recommended hardware, and if so, is it worth it?
A common approach to overcoming analysis paralysis is to push your questions to your supervisor. Let them make the executive decisions, as they have more experience. The problem with this approach is that it discourages independent thinking, significantly slows down your development speed, and wastes your supervisor’s time.
To overcome paralysis analysis, spend a few minutes thinking through the problem yourself and weighing the pros and cons. Write down your thoughts on the consequences of the design and complexity of the expected implementation. If there is a clear winner, then problem solved!
Here is the key insight: if there is not a clear answer, pick the one that is easier to implement and then implement it. Submit a pull request and describe to your reviewer what you did and how they can test it. Then ask the reviewer if your solution works or if you should make any changes to your design.
By doing this, you change the discussion from:
- “Should I choose design A or design B?
- “What is design A and what is design B?”
- “Design A would be … Design B would be…”
- “Would that cause issue XYZ?”
- “I’m not sure, maybe…”
- “I have implemented design A, which you can test by…. I have considered making modification B to…”
- “I just tested it. I think that A is better, as B would…”
- “Should I consider making these modifications that would increase XYZ?”
- “No, XYZ would cause…”
At the end of the day, software developers are implementers; they bring ideas into reality. If you can’t decide, then implement the easier solution to allow your reviewers to test it out and give you feedback that will lead to actionable tasks moving forward.
By following this approach, software developers will be empowered to make their own decisions, implement solutions faster, and most importantly, allow others to test their code and give them real, concrete feedback.
Here is an example of a pull request that uses this methodology. A working solution is fully implemented to allow the reviewer to test the code, while the description asks meaningful questions that the reviewer can easily answer; they don’t have to talk about abstract ideas, but can really try it out.
Documentation: Tutorials and Example Code Are Key
In software development, documentation is key. This rings true even more for open-source work. When your software will be used by thousands of roboticists and developers across the world, you must document your code in a manner that allows users, with varying levels of software experience, to easily customize the software to their specifc needs.
While technical documentation is very important, for obvious reasons, it is not the first place that a new user will look at; the first place they look is the tutorials and example code, which makes this the most important aspect of open-source software documentation.
In general, users rarely make changes to the lower-level aspects of the software. The typical user will follow tutorials and read through example code to customize the software to their specific needs; they only look at the code in detail if they have a problem. If the solution can’t be easily discovered after following the tutorials and example code, there is a very good chance that the user will give up.
Give your users a big list of libraries and they will get bored before accomplishing anything. Example code and tutorials are the key.
By constrast, give your users step-by-step instructions describing exactly how to make something work, and they will be motivated to work off of the examples to create something great. They will be motivated to read through the technical documentation once they see how easily they can make something work.
Here is an example of a tutorial done right. It has step-by-step instructions that allow new users to get up and running easily, but also contain in-depth tutorials and examples that show users how they can customize the software further.
The last three and a half months was filled with amazing learning experiences and memorable moments. Thank you to Google Summer of Code and Open Robotics for giving me the opportunity to work on this project. This summer has sparked my passion for open-source software, and I am excited to continue contributing to VRX.