Software development is more than just writing code. Learn about organizing and packaging projects to be more accessible to other developers in this talk presented by SuprTEK. Discover what makes an easy-to-compile and distributable code base.
2. • There will be a slide with links and a QR code at the end of the
presentation
Save Photos Until the End
SuprTEK Advanced Technology Group 2
3. • Version control
• Core documentation
• Project structure
• Code modularization
• Good frameworks and libraries
• Fast, simple builds
• Thorough testing
Components of a Successful Project
SuprTEK Advanced Technology Group 3
5. • Project history
• Disaster prevention
• Reduced clutter
• Smaller footprint
• Faster navigation
The Benefits of Version Control
SuprTEK Advanced Technology Group 5
6. • Easy collaboration and contributions
• Ability to access your code wherever you have an internet connection
• Free backups
These sites are popular for hosting repositories:
• BitBucket
• GitHub
• GitLab
Host Your Repositories
SuprTEK Advanced Technology Group 6
7. • Help other developers figure out what you’re doing
• Good commit messages are:
• Short
• Descriptive
• Consistent
• Conventions vary by version control system
• Look them up and follow them
Commit Messages
SuprTEK Advanced Technology Group 7
8. • Maintains correct dependencies between projects
• Keeps a clear list of when fixes or bugs occurred
• Allows stable versions to be accessed with ease
Tagging and Versioning
SuprTEK Advanced Technology Group 8
10. • A license file contains the text for the license your code is released
under
• Developers will not contribute to a project with no license
• Spend a few minutes (or more) to decide upon a license
• Licenses are often not compatible with certain projects; choose one that
makes sense for your current use
• You can read up on software licenses here: https://tldrlegal.com/
Create a LICENSE File
SuprTEK Advanced Technology Group 10
11. • README files are displayed by default by most repository hosts
• Developers will go to a readme file before anything else
• READMEs should include:
• Basic download/use instructions
• Compilation instructions
• Limitations or prerequisites (“Only runs on Windows” or “Requires JDK 1.8”)
• Other useful sections include:
• Project structure
• Links to more detailed resources (Wikis, FAQs, Issue Trackers, etc)
Create a README File
SuprTEK Advanced Technology Group 11
12. • When a project becomes large enough, a contribution guide sets a
standard for all developers to follow
• It should detail:
• Code style
• Branching and merging guidelines
• Naming conventions
• Anything else you feel contributors should know
Build a Contribution Guide
SuprTEK Advanced Technology Group 12
13. • Change logs are great for non-contributors
• Tracks features and bug fixes present in each release
• Can serve as a short-term roadmap for upcoming features
Keep a Change Log
SuprTEK Advanced Technology Group 13
14. • Make a design document available
• Provide a roadmap for short and long-term goals
• Use an issue tracker, checklist, the back of your hand to stay on
track
• Link to these documents/sites in the readme or contribution guide
Plan for the Future
SuprTEK Advanced Technology Group 14
16. Following conventions helps other developers familiarize themselves
with your code much faster.
Be particularly mindful of:
• Source folders
• Resource folders
• Test folders
• Dependency folders
Follow Language Conventions
SuprTEK Advanced Technology Group 16
17. • Place core documentation in the repository root
• These core files include:
• Readmes
• Change logs
• Contribution guides
• License files
• All other documentation should have dedicated folders
Separate Documentation
SuprTEK Advanced Technology Group 17
18. • Anything you build or compile should be hosted elsewhere
• Binaries add bloat to repositories
Don’t Include Binaries
SuprTEK Advanced Technology Group 18
19. • Modularizing your code makes it easier to find what you want in
larger projects
• It also helps in keeping reusable code in one place
Modularize Your Code
SuprTEK Advanced Technology Group 19
21. If your code is public:
• Keep your projects that work together in the same repository
• If necessary, create a library as a separate project and publish it
Keep it Together
SuprTEK Advanced Technology Group 21
22. If you have multiple applications that don’t depend on each other:
• Make these their own repositories
• If your project is large enough, consider starting a group or
organization on your repository host
If your code is private:
• Split major components into their own repositories
• Make sure they still build on their own
Keep it Apart
SuprTEK Advanced Technology Group 22
23. • These are areas of code that appear in multiple places
• Usually in the form of:
• Interfaces
• Abstract classes
• Plain data objects
• Helpers and utilities
• Database access layers
• Multiple common modules can exist if needed
Identify Common Functionality
SuprTEK Advanced Technology Group 23
24. • Utilize modules or sub-projects to separate code that’s common
across multiple areas of functionality
• For example:
• A ‘common’ module containing interfaces
• A ‘database’ module that implements the interfaces in the ‘common’ module
• A ‘server’ module that uses the ‘common’ and ‘database’ modules—the ‘database’ module’s
implementations are injected by the application server
Create Sub-Projects or Modules
SuprTEK Advanced Technology Group 24
Application
Server
Server
Module
Database
Module
Database
Module
Server
Module
Injected IntoInterfaces
26. • Use well-known, popular frameworks and libraries
• Odds are, they’re popular for a good reason
• Other developers are more likely to be familiar with more popular
libraries
Go With the Flow
SuprTEK Advanced Technology Group 26
27. • Making developers learn new libraries slows their contributions
• These libraries may have obscure bugs or poor performance
• They may not be updated if future compatibility issues arise
• Bugs may never get fixed
Don’t Pick Obscure Frameworks/Libraries
SuprTEK Advanced Technology Group 27
28. • Sometimes a new or obscure library can fit your needs better than
anything else
• Try it out and see!
…Except When You Should
SuprTEK Advanced Technology Group 28
29. • Larger dependencies means longer downloads
• Large downloads are painful when working on a slow connection or one with
data caps
• Size limitations may exist on some targeted platforms
• An 11MB localization library may not be a lot until you’re limited to a 50MB
Android package
• The benefit of a library may not outweigh the extra space
• Consider if you need a library before adding it to your projects
Be Mindful of the Size of Dependencies
SuprTEK Advanced Technology Group 29
32. • Keep them all in a single location, preferably near the root of your
directory structure
• Provide detailed instructions for installing them
• If your project targets multiple platforms, ensure the dependencies
are included for each platform
…But If You Must
SuprTEK Advanced Technology Group 32
33. • Dependency managers download and inject dependencies
automatically
• They enforce versions and sub-project inheritance
• You can get back to writing code faster instead of configuring paths
and build tools
Use a Dependency Manager
SuprTEK Advanced Technology Group 33
35. • Only a few commands (at most) should be necessary to build a
project
• If this is not possible to do, consider creating scripts or using
different build tools
• Keep the time to download, build, and run a project for the first
time under 15 minutes
• Don’t require other dependencies to be compiled or installed—
especially outside of a project
• If other modules in the same project are required, include those in
the build process automatically
Keep it Simple
SuprTEK Advanced Technology Group 35
36. • A build should not require configuration outside the project
• Requiring outside configuration vastly decreases build compatibility
with other systems
• Sometimes this is unavoidable, depending on the language and
dependencies
• Attempt to minimize this configuration
System Configuration is Bad
SuprTEK Advanced Technology Group 36
37. • A build should produce a usable (runnable or deployable) artifact
when complete
• Requiring further manual steps to use an artifact wastes time and
frustrates developers
Create Something Useful
SuprTEK Advanced Technology Group 37
39. • Borrow a friend’s
• Ask a friend to try things out
• Fire up a virtual machine
• Use a free Amazon Web Services account
• Wait for complaints to accumulate in your issue tracker
Build on a Clean System
SuprTEK Advanced Technology Group 39
40. • If a project targets multiple platforms, perform a build on each one
• Follow your build steps precisely and update documentation when
needed
Test Other Operating Systems
SuprTEK Advanced Technology Group 40
41. • Many build tools automate testing
• Core functionality needs to be tested; other tests should be
optional
• Avoid platform-specific tests if possible
• Allow manual running of tests
• Run all tests (including optional ones) before performing a release
Include Tests in Build Process
SuprTEK Advanced Technology Group 41
42. • Don’t let a build pass when it fails tests
• This prevents accidentally releasing buggy code
• If the build process fails due to a bad test, fix it or remove it in a
timely manner
…And Fail the Build When the Tests Do
SuprTEK Advanced Technology Group 42
43. • Deploy or run projects on every platform it’s targeted for
• Ensure functionality is present and the same for each platform
• Document any extra steps taken for deploying
Deploy, then Deploy Again
SuprTEK Advanced Technology Group 43
44. Your repository should now be:
• Accessible
• Maintainable
• Well-organized
Pat Yourself on the Back for a Job Well Done
SuprTEK Advanced Technology Group 44
46. • Explore, evaluate, and develop new technologies that
can be applied to our clients’ missions
Research & Product
Development
• Apply capabilities from R&PD to develop solutions that
solve client-specific problems
Solutions
Architectures
• Provide tactical consulting services to address
technically-challenging requirements on client programsConsulting Services
• Optimize and maintain IT infrastructure and security to
support and enhance business operationsIT Infrastructure
Building Stuff Our Clients Wish Existed…