Skip to content

Development Environment / Tips and Tricks

This documentation provides tips and tricks to increase efficiency and reduce frustration.

Introduction

"Back in the day", software developers needed to understand only a few programming languages, computer environments, and software tools. Although computer environments have consolidated (Windows, Linux, Mac, Android, iPhone, etc.), software languages and environments have proliferated. Consequently, it can be challenging for full-time software professionals to understand technologies, and even more so for occasional programmers.

This documentation is intended to provide nuggets of useful information that may help developers be more efficient and reduce frustration dealing with technologies. It is not possible to provide a full description, so readers should use other internet resources as needed.

Understand how to a command line interface works

Desktop computer operating systems (e.g., Windows, Linux, Mac) implement similar general design concepts and features. Each operating system now provides a window-based interface, consisting of a "desktop", menus, windows, and other visual components. A mouse or other pointing device is used to navigate a windows-based interface and a keyboard can be used to type text. Although windows-based desktop environments can be useful, they hide useful operating system features.

Operating systems also include a "command line interface" (CLI), also called a "shell" or "terminal". The following figure shows a Windows "Command prompt" window, which can be opened by searching for cmd in the Windows desktop search tool.

Windows cmd window

Windows cmd Window (see full-size image)

The following shows a Git Bash command shell running on Windows, which can be opened by searching for bash in the Windows desktop search tool. The name Bash is from "Bourne Again Shell", which is derived from an older "Bourne Shell".

Git Bash window

Git Bash Window (see full-size image)

Command shells, terminals, command prompt windows, etc., consist of a text based interface to interact with the prompt, and a graphical user interface consisting of the window, which integrates with the operating system's windowing environment. The window typically provides a way to change settings such as font size and colors, and provides copy and paste features. When in doubt, try right-clicking on different areas of the window to see if a pop-up window will display.

The command line interface (shell) works as follows:

  1. Show a text prompt and wait for user input.
  2. The user must type input and use the keyboard's Enter key (also called Return) to tell the shell to use the input. The input is expected to be a program name followed by space-delimited command parameters (also called arguments and options).
  3. The shell will use the $PATH environment variable to determine which folders should be searched to find software.
    1. If the program is not found, the shell will output an error. The program documentation should explain the recognized command parameters.
    2. If the program is found, it will be run:
      • The operating system passes the command name and parameters to the program, for example in argc and argv variables, with the names varying by programming language.
      • The starting folder will be used when relative paths are used for files in the program. Mistakes in file paths are a common error.
      • Any errors will be the result of the program's logic.
      • The program exits when done and passes an "exit code" to the operating system, which is the ERRORLEVEL (%ERRORLEVEL%) environment variable in Windows and ? ($?) in Linux. An exit status of 0 usually indicates success, and a non-zero value provides an error code, which should be documented to help with troubleshooting.

Although various operating systems use different words, the concepts are similar. For example, a "directory" is equivalent to a "folder", and the latter is easy to understand given the use of folder icons and equivalent physical folders in filing systems. This explains why the cd (change directory) command is available on Windows and Linux. However, the behavior of cd is different. On Windows, cd shows the current folder (similar to pwd on Linux) whereas on Linux, cd changes to the user's home folder. These differences become familiar over time can but can be confusing. See the following lists of common commands and programs used in StateMod development:

Understand user files for different environments

Each operating system environment (Windows, MinGW, Linux, etc.) has standards for where files exist. In some cases, the environment will store user files separately. In other cases, user files are the same but are accessed with a different path. The following tables summarizes differences for environments used with StateMod development. See also the cygpath command available in each environment (see Linux Commands and Windows Commands).

Environment Shell User Home Folder User Files Shared with Windows?
Windows cmd C:\Users\user Yes - same.
MinGW bash /home/user No
Use /c/Users/user to access Windows user files.
Git Bash bash /home/user Yes
Also use /c/Users/user to access Windows user files.
Linux bash or other /home/user No
Separate machines.

Pick a good text editor

The StateMod development environment currently does not use an integrated development environment (IDE) and relies on editing text files and running command line programs. The Eclipse IDE is an option but has not been fully integrated for development but may be fully adopted in the future. StateMod input and output files are also text files. Consequently, a text editor is necessary.

Text editors are not created equal and software developers tend to use different editors than non-developers. For example, Visual Studio Code provides features for software developers whereas Notepad++ is simpler. The vim editor is "old school" but provides features that increase efficiency and are useful on remote text-only computer sessions. Developers that work on Windows and Linux tend to choose editors that work on both.

If the text editor that was initially chosen for development is limiting efficiency, research whether the editor has advanced features that need to be learned, or try another editor.

See the Development Environment / Text Editor documentation for information.

Use command shell aliases and scripts for common tasks

Repetitive tasks, especially multi-step tasks, can be improved using shell aliases and scripts.

Linux Aliases

An alias can be added to Bash shell by adding the following to the ~/.bashrc file (/C/Users/UserName/.bashrc, where the file is on the same drive as user files). For example, the following alias defines a command cdcd that changes to the location of CDSS development files on the computer an then lists the files.

# Helpful aliases for CDSS standard development environment.
alias cdcd='cd /d/Users/steve/cdss-dev ; ls'

Open a new Git Bash window after adding the alias and then type cdcd to change directories to CDSS development files. Other aliases can be added as desired.

Linux Scripts

Linux Bash scripts can be created to automate many tasks. The StateMod development environment includes scripts to perform tasks such as building the software installer. Learning Bash is a worthwhile investment and many resources are available on the internet.

Windows Aliases

Windows does not provide aliases, but a command file can be used. For example, to create an "alias" to change to the CDSS development folder:

  1. Create a folder to save command files (e.g., C:\Users\UserName\bin).
  2. Create a simple script like the following named cdcd.cmd.
  3. Use the Windows Search field to search for "path" and then edit the PATH environment variable to include %USERPROFILE%\bin.
  4. Start a new cmd shell.
  5. Type cdcd at the prompt to run the command file.
rem Simple command file to change to CDSS develop folder and list the files.

@echo off
cd %USERPROFILE%\cdss-dev
dir

Windows Command Files

Widnows cmd command files can be created to automate many tasks. The StateMod development environment includes command files to perform some tasks. Learning how to define command files (batch files) is a worthwhile investment and many resources are available on the internet.

However, Windows command files that do more than simple tasks can be frustrating. If a Linux environment is available, such as the MinGW environment used with StateMod development, or Git Bash, writing Bash scripts tends to be better.

Use AI to learn

Artificial Intelligence (AI) tools are now available that can help with education. In many cases, AI simply provides a better search engine for complex information and is able to link concepts and present information using language and images. For example, ChatGPT and other AI tools can be used to ask questions about a programming language and other technologies. This is possible only if public documentation is available to train AI.

Any topic mentioned in this documentation, including Fortran, Linux, Git, etc., can be searched using AI tools. However, examples that are provided are often incomplete and can be wrong. It is also often not clear what version of a technology has been used so questions that are posed may need to be specific. Therefore, when using AI, make sure to use critical thinking to evaluate the answers and do not just copy and paste the output into code without understanding and testing the code.