APPLICATIONS

  • 01/10/2019
    6:00 AM
  • Rating: 
    0 votes
    +
    Vote up!
    -
    Vote down!

Coding for Others

Writing code with the mindset that others are going to view and contribute, even for personal projects, improves the overall project and provides benefits to yourself.

Learning to write code outside of a formal setting such as a University is often done using online self-paced courses. Self-paced courses are a great way to learn the syntax and some nuances of a programming language and hopefully provide that first step to your first coding project.

Personal projects and self-paced courses are a great way to learn to program, and it is how many people shift from an operations role to a role more focused on development. The code you write is written for you, by you, and no one else. Writing code for yourself might be maintainable by yourself but lacks information that can help other people.

(Image: Pixabay)

Writing code for others helps other people understand the project and some of the decisions you have made. It also helps you pick up the project again six months later.

This article addresses methods to help you move away from coding for yourself to coding for others.

Create a plan

Consider what the end state of the project should look like and create a plan as to how you’re going to get there. The plan should include a rough outline of tasks and sub-tasks that need to be performed to achieve the end state. These tasks become functions.

When considering the tasks, think about what information is required by each task for it to fulfill its purpose.

The above method strategy for creating functions is nothing new and part of normal development. However, when writing code for others, it can be beneficial to document the key points of your thought process, resulting in initial documentation of the ‘why’ behind your function designs.

Version Control

The ability to track changes and manage incoming changes to a code base is critical when working with others. Part of the planning process should include creating guidelines on how others can contribute to the project.

Documentation

Open source projects typically follow a pattern when it comes to documenting projects. There are a small number of files that are expected to exist. A consistent approach to documentation makes it easier for other people to find what they require and understand the project. Projects have two scopes for documentation: project level and code level.

Project level documentation is usually written in markdown formatted files such as README.md and INSTALL.md. This level of file covers the project as an entity. A project plan provides most of the information required to create initial project level documentation.

Code level documentation is located within modules and describes the code itself and specifies dependencies. Programming languages include their documentation standards within their code style documentation.

Well documented contribution guidelines are essential when working with others. These documents set the expectations for contributions and help ensure consistency.  Typically, these guidelines are contained in a file called CONTRIBUTING.md.

Contribution guidelines provide instructions for tasks to be completed before attempting to merge code changes into the main code base. Your project might require unit tests for new code, linting, and doc strings for new code.

Keep Code Clean

Writing code that is clean requires the combination of several disciplines and takes time. However, clean code is easier to read and work with than poorly written code. Clean code is an indication of good project planning with a clear intent.

At the very least clean code needs modularity, single-purpose functions, and good consistent naming conversations.

Modularity and single purpose functions encourage code reuse and efficiency in the writing process. Additionally, modularity simplifies the maintenance and troubleshooting process.

Write tests

Unit tests are used to test that functions and classes return an expected result based on a given input. During execution, the internals of a function aren’t that important (within reason) if the output is correct based on the input.

Over time the code base is going to change through refactoring to improve reliability, performance, or bug fixes. As this happens, we need to ensure that our functions continue to return the same result when given the same inputs. This is the function of unit testing.

For example, we have a function that which takes in two integers, adds them together, and returns the result. The unit test contains a list of predefined inputs and the expected outputs for the sets of inputs. It would execute the function and compare the returned result against the expected value if the returned value and expected value match the test pass.

The above usage of testing can be used to validate input filtering and demonstrate that a function raises an exception when expected.

Summary

Writing code with the mindset that others are going to view and contribute, even for personal projects, improves the overall project and provides benefits to yourself.


We welcome your comments on this topic on our social media channels, or [contact us directly] with questions about the site.

Log in or Register to post comments