Sharing Coding Projects

Project based thinking #

Programmers are typically learning to write source code to build programs not just scripts. A programming project requires far more than just fluency with a particular programming language syntax to cohesively put together.

Creating a program requires certain executive functioning skills to coordinate and manage. This guide provides some advice and items to consider include when sharing your codebase. It is not meant to be followed religiously, but instead to provide a framework to guide your approach.

Programming is an activity that starts with a specification and leads to its solution as a program - Peter Van Roy

Programming as an activity #

  • Programming can be done in micro (small tasks) or macro (very large projects)
  • Programming can be language independent architectural issues, and language-depended coding issues
  • Programming should be unbiased by limitations of any particular language, tool or design methodology

Planning before you begin coding #

You need to first figure out what needs to be built, by gathering the requirements.

  • What do you want to make? - can you describe the problem? how are you solving it?
  • Sketch out your ideas - how many classes are needed? how many functions?
  • What technologies will you use? You need to consider which languages, libraries, or environments you’re familiar with or willing to learn.

Software Development Life Cycle (SDLC) #

A common model for presenting the phases of building software goes by the name of Software Development Life Cycle or SDLC for short. This models covers the principles of building a software application, which includes various phases of activities such as planning (such as gathering spec requirements), scheduling the work, development, and test. The name for this set of phases is called Software development lifecycle (SDLC). Some of these phases are described below.

  • Requirements Gathering

    It helps to know what you’re building before you begin building. Deciding what to build should come from discussions with

  • Scheduling
  • Design / Specifications
  • Building
  • Testing
  • Deployment

What is a README? #

This is a file that is named README, that usually resides in the root of your project directory. This name comes from the command Read me. as in the situation of handing a project off to another developer and writing a memo to them that should be read first before the source code.

In a way, it serves as an executive summary of your project. It gives your reader a chance to understand what’s going on since source code doesn’t describe the intent and purpose of projects very well.

What should go into a README? #

The readme should contain description about what the project is about, and also information to build and/or run your program.

An example of a barebones README can be found at https://github.com/cisc3130-s20/assignment-template

Within this file it starts with the title of the project, followed by instructions for setting up a development environment and then some info on where code can be saved.

There’s generally no industry standard on the order sections should go or how to name the sections. It’s generally based on what makes sense to you, and/or what you think would help your reader.

Formatting a README #

This file is usually a text file. It can be written in plain text, however you can also choose to use some sort of formatting if you’re publishing your project on GitHub and the like. That formatting is called markdown - it is a way to help your text be more readable on the web page.

For example, if you want to add a title to your markdown you can use a single # symbol to mark it as a heading level 1 (top level). You can add inline code snippets using the ` character or a code block with three ticks as fences around the section.

The other formatting possibilities like bold and italics is a lot like formatting chat messages in discord and slack, with a mixture of _, *, ~ symbols to mean varoius things. Take a look at the markdown page for more guidance.

Read more about READMEs #

Checklists #

Elements to include with your project repository #

Note that these items do not include anything about documentation, which should also be included with coding projects.

[ ] 1. Project description #

  • Description of the program such as a README file
  • Project requirement(s) and tracking. Sample approaches listed below:
  • Instructions on how to run your program or code
  • Description of technologies used

[ ] 2. Source code with comments #

  • Comments describe why each class and function exist
  • Comments describe any conditional or control flow logic

[ ] 3. Submit to the form before deadline #

  • Link to your code (you can use any platform. GitHub is common)
  • Repository is either public, or you’ve added me as a collaborator

“Writing documentation is like saving for retirement. It’s hard to tell if you have enough at the time you’re doing it. Only later can you tell if you have enough, and usually you wish you had more.” -J.Wirth

Elements of Style and Presentation #

  • Clean Code
  • Indentation throughout code is uniform
  • Sensible comments
    • Comments are included with each method, to describe why it exists
    • Input parameters and output parameters described
    • Comments describe classes
  • Variable names make sense

Other Enhancements #

Nice to have

  • Sensible commits
    • Each commit to version control makes sense
  • Testing
    • Prepare a brief description of test cases to run on your code
    • Prepare scripts/code for running the tests
    • Report on the test cases

Elements included with your submission:

  • Project description
  • Instructions on how to run your program or code
  • Description of technologies used

References #