Building foundations

Building Foundations
MITCHELL MATTHEWS

• 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

• Version control
• Core documentation
• Project structure
• Code modularization
• Good frameworks and libraries
• Fast, simple builds
• Thorough testing
Components of a Successful Project

Version Control

• Project history
• Disaster prevention
• Reduced clutter
• Smaller footprint
• Faster navigation
The Benefits of Version Control

• 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

• 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

• 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

The Basics

• 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

• 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

• 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

• 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

• 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

Project Structure

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

• 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

• Anything you build or compile should be hosted elsewhere
• Binaries add bloat to repositories
Don’t Include Binaries

• 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

Modularizing Code

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

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

• 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

• 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
Application
Server
Server
Module
Database
Module
Database
Module
Server
Module
Injected IntoInterfaces

Frameworks and Libraries

• 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

• 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

• Sometimes a new or obscure library can fit your needs better than
anything else
• Try it out and see!
…Except When You Should

• 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

Packaging Dependencies

Don’t Do It!

• 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

• 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

Make Builds Easy

• 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

• 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

• 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

Testing Things Out

• 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

• 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

• 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

• 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

• 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

Your repository should now be:
• Accessible
• Maintainable
• Well-organized
Pat Yourself on the Back for a Job Well Done

Download:
http://www.slideshare.net/MitchellMatthews/building-foundations
The Photo Slide
My GitHub Account: https://github.com/KrazyTheFox

• 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…

Building foundations

Recommended

More Related Content

What's hot (20)

Similar to Building foundations (20)

Recently uploaded (20)

Building foundations