Guidance for setting up your mac, specific to our lab, is avilable here.
You should also go through our tutorial on getting setup for LaTeX.
Document as You Go
Use a lab notebook. Some people prefer hard bound notebooks, and others digital. Digital notebooks are much easier to search, tag, organize, and reuse and can more easily include photos of whiteboards, screenshot, code snippets, etc. I use Markdown files.
Create theory documentation (in addition to usage documentation) for any code you write. Any derivation you do in your notebook that is used in your code, should be transferred to an electronic format attached with the code (again, made easier if the notebook was digital to begin with). It is very common to revisit your code later, or for someone else to want to build on it. If the theory isn’t carefully documented it’s going to be very hard to remember what you did or for someone else to try to figure it out. A few minutes now will save you hours later (both for modifying code later, and for writing the methodology in your papers). I like to follow the four separate purposes of documentation. Here are some suggested formats:
Documenter.jl: For Julia this should be your default. It is markdown-based and easy to use.
README: if the module is very simple and only requires a short amount of documentation (e.g., a wrapper module) a README file will suffice or a README and a couple of markdown files. (Even with other documentation options you should still always have a README to provide some a basic explanation of what the module does and how to get started).
LaTeX PDF: Extensive theory is probably best documented separately in LaTeX because you can cross-reference equations, references, etc. You can then refer to it in your main documentation.
Use Docstrings and learn what the expected format is for your programming language.
Comment your code. Refer to where you found equations/values (e.g., reference your documentation or a textbook/paper).
Beginners often have one comment line per 10 lines of code, excellent programmers invert that ratio (considering docstrings, theory, etc.).
Version Control and Backup
Version control is essential. We use version control to develop code, to write papers, to collaborate, to rollback changes, etc. Use good commit statements so that you have a useful version history. Version control is helpful even on individual projects.
Our lab uses GitHub to host our repositories. If you are actively working in our research group, sign up for a GitHub account and send me your username so that I can add you to our team.
For stand alone codes, our repository naming convention is all lowercase. Avoid separators where possible, but if it will help readability use a dash to separate words, not an underscore.
For a paper and associated code, our naming convention is leadauthorlastname[year]-shortdescription (i.e., ning2017-airfoil).
Archive results in addition to the code that produced it. Also archive the code that you used to create plots. This will save you a lot of time when regenerating plots. Plot regeneration is often needed to create versions of your plots for your presentation, or in responding to peer-reviewer’s suggestions on your publications.
Backup. You must have your data, code, etc. backed-up in at least one other location and preferably two other locations. At some point you will lose data if you do not have backups. I recommend Dropbox (continuous cloud-based backup) or Box (for which we have an university subscription).
Code Development
Document and comment your code in detail as you go. I said this already, but it is important and rarely done enough!
Unit Test! All major programming languages have easy to use unit test frameworks. You need to test your code anyway so encapsulate the tests so you can run them later and help ensure correctness as you refactor later. As you update code be sure to update your unit tests as well.
Make effective use of whitespace and other delimiters to group logical sections together and make your code easier to read.
Use descriptive variable names.
If you find yourself writing a very similar piece of code more than once, you should refactor the code to create one function used in multiple places. Having duplicate code opens up additional opportunities for bugs with version mismatches.
Don’t try to write a large program all at once. Break it down into small pieces. For each small piece be sure to thoroughly verify and validate (V&V) it before moving on. In this way you can build up large complex codes.
As you get a little more advanced and are ready to share code with others see the guidelines on package development.
Project Management
We often use GitHub for more than just version control. We also use it to track and discuss tasks and bugs through Issues, organize and visualize project progress, and perform code reviews.
