Capstone Project Wiki

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
<-Requirements Artifacts^.:home|Artifacts^Test Artifacts->
=====Software Artifacts=====

See also [[..software_projects:home|Software Projects]].
====Source Code====


<html><div class="capnote">
NOTE: Capstone seldom asks you to turn in <i>listings</i> of source code.  The computer files are the important artifacts here.  We generally only want links to repositories or directory trees.  For relatively small sections of critical code, or where the sponsor requests it, source code listings may be required.
</div></html>

As you work on projects that involve microprocessors, embedded controllers, or any other kind of computer as part of the product, you will need to create appropriate software as part of your product.  Source code (along with the appropriate compilation and linking utilities and instructions) form the product definition for the software component of the product.  Input from your sponsor is especially important for choosing languages, software development tools, and programming styles.

Source code that is poorly managed leads to extreme difficulty in maintaining and improving the product, particularly late in the design cycle.  Therefore, good practices should be followed when working on software development as part of a product development project.

The following guidelines can help tackle the complexity of software projects.

====Use Appropriate Languages====

The languages and compilers you choose to use can have significant influence on the long-term usability of your product.  Be sure that you ask your sponsor if they have any requirements or suggestions for the language and compiler you use.  Using tools that are appropriate for the sponsor will allow your product to be integrated much more tightly with the sponsoring organization. For example, Python can be great for scientific computing in a university environment, but it may not be deployable in the cloud framework of your sponsor.

====Use Revision Control====
Source code is constantly changing, and as it changes, its behavior changes, both intentionally (due to added features) and unintentionally (due to added bugs).  This means that any report on the state of the software is potentially only valid for the exact version used.  Thus, your software needs effective revision control.  Keep multiple backup copies.

A number of revision control systems (RCS) exist, in both commercial and noncommercial form.  One of the most popular systems is git.  git allows you to save multiple versions of your software and instantly switch between versions.  If you don't have another RCS that you or your sponsor prefers, we recommend that you use git.  To get started, you may want to look at [[https://git-scm.com/book/en/v2/Getting-Started-Git-Basics|getting started with git]].

====Always Back Up Your Software====

Your source code represents hundreds of hours of work. Failure of a hard drive could cause all that work to be lost in an instant.  To protect against this eventuality, be sure to have an effective backup process in place that stores copies of your work on different media and in different locations.

Your revision control system may be able to help here. In particular, git makes it trivial to clone your code into as many different places as you'd like.  For example, you could store your code in GitHub, GitLab, Box, your personal laptop, and a USB drive.  The chances of all these systems failing simultaneously are vanishingly small.  Before using off-campus resources to store code or other sensitive information, obtain specific approval from your sponsor to use the desired resource.

====Provide Build Documentation and Scripts====

The source code itself is of limited use if the person who picks up where you left off has no instructions on how to compile the software, install it on the appropriate system, and complete any other necessary tasks to use the software with your product.

If you are using a visual (graphically-oriented) development system, you may need to just describe the mouse clicks necessary to make things work.  This is a minimum standard, but leaves open the possibility of human error.

A more powerful approach is to create appropriate build scripts that use a single command or executable file to complete the entire build process.  If you can create a build script, the chances for error are greatly minimized.

A good test of your build documentation is to have a member of your team who is computer-savvy but not part of the software development team try to follow your instructions to build the software starting from a brand-new copy of the code. This is a good test of transferability for a software project.

====Comment Source Code Appropriately====

Comments are helpful in understanding source code, but there's always a risk of the comments getting out of sync with the code.  To avoid this problem, consider the following:

  * Use descriptive variable names (e.g.,MeasuredPower instead of P) and function names.
  * Try to keep functions short (less than a page, if possible)
  * Use comments to identify any tricky algorithms, but not to explain obvious things. For example,\\ ''MeasuredPower = MeasuredVolts * MeasuredAmps''\\  should not have a comment.  But a block of code that is used to find the root of an equation using the Newton-Raphson method might benefit from a comment.

====Use a Standard Coding Style====

Ask your sponsor what code style guidelines they prefer (e.g., spaces vs tabs for indents, the number of columns to indent, the locations of braces and other enclosing items).  If they have guidelines, follow them religiously.

If sponsor does not have guidelines, you should identify and adopt your own guidelines and follow them religiously.   Possible guidelines could include the GNU coding standards, PEP 8, or the ECEn coding standards for [[https://byu-cpe.github.io/ecen330/other/coding-standard/|C]] or [[http://ecen220wiki.groups.et.byu.net/03-coding-standard/|SystemVerilog]].

Following standards helps everybody associated with the project to better understand the code and  be able to make appropriate changes.
Capstone Project Wiki

User Tools

Site Tools

Page Tools
