Building foundations

Building FoundationsMITCHELL MAT THEWS

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

SuprTEK Advanced Technology Group 3

• 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

9


• 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

https://tldrlegal.com/

https://tldrlegal.com/


• 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

ApplicationServer

ServerModule

Database Module

DatabaseModule

Server Module

Uses

Implements

Injected Into

Deployed

Deployed

Interfaces


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

44

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

http://www.slideshare.net/MitchellMatthews/building-foundations

http://www.slideshare.net/MitchellMatthews/building-foundations

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 problemsSolutions

Architectures• Provide tactical consulting services to address

technically-challenging requirements on client programs

Consulting Services

• Optimize and maintain IT infrastructure and security to support and enhance business operations

IT Infrastructure

Building Stuff Our Clients Wish Existed…

Building foundations

Software