Software Engineer Resources

For research software engineers, Good Research Code is a good primer.

Guiding Principles

In developing software at the Allen Institute, we have a set of guiding principles that promote Team Science and Open Science, which helps us define our best practices.

• Software development should be collaborative, and code should be maintainable by more than one person

• End users should be able to run our code and understand how to run it through documentation and tutorials

• If a user discovers a bug or wants a new feature added to a package, they should know how to request support, or feel welcome to contribute to a repository

Software Design Patterns

In writing software, many recurring problems exist that cannot be solved through library encapsulation because of the problem’s nuances. In such cases, however, they can frequently be solved by leveraging one or more existing Design Patterns.

Design Patterns are vetted approaches to solving recurring, related problems. They describe a way to structure and organize code. Design patterns are expressive; they communicate intent to other contributors reading and writing code. (This is in contrast to “spaghetti code.”)

The following is a loose collection of software design patterns. This list is not exhaustive. It is intended as a starting point to approaching new problems by first investigating what patterns may be relevant.

• Object Oriented Design Patterns

  • Creational: object instantiation

    • Factory

    • Singleton

    • Dependency Injection (aka: passing in objects to other objects as parameters)

  • Structural: object internal and external composition

    • Acyclic Dependency Principle

    • Model-View-Controller

    • Model-View-ViewModel

    • Separation of Concerns

  • Behavioral: object interactions

    • Observer

    • Ask for forgiveness instead of permission EAFP over LBYL

  • SOLID Principles and original paper (PDF)

• Communication Patterns

  • Adapter

  • Request-Reply

  • Publish-Subscribe

• Database interactions

  • CRUD

Other resources

• Refactoring Guru’s Catalog of Design Patterns

• Thread-Safe Design Patterns

• Geeks for Geek’s intro to Low Level Design

Other Code Review resources

• Microsoft ISE Engineering Fundamentals Playbook Code Reviews

• Jetbrains Qodana Python Code Review Checklist (With Examples)

• MIT 6.005 Software Construction Reading 4: Code Review