1# Code Management 2 3We list some of the techniques that may be used to increase one's 4efficiency when developing PETSc application codes. We have learned to 5use these techniques ourselves, and they have improved our efficiency 6tremendously. 7 8## Editing and Compiling 9 10The biggest time sink in code development is generally the cycle of 11EDIT-COMPILE-LINK-RUN. We often see users working in a single window 12with a cycle such as: 13 14- Edit a file with `emacs` or `vim`. 15- Exit `emacs` or `vim`. 16- Run `make` and see some error messages. 17- Start `emacs` or `vim` and try to fix the errors; often starting 18 the editor hides the error messages so that users cannot remember all 19 of them and thus do not fix all the compiler errors. 20- Run `make` generating a bunch of object (.o) files. 21- Link the executable (which also removes the .o files). Users may 22 delete the .o files because they anticipate compiling the next time 23 on a different machine that uses a different compiler. 24- Run the executable. 25- Detect some error condition and restart the cycle. 26 27In addition, during this process the user often moves manually among 28different directories for editing, compiling, and running. 29 30## Several easy ways to improve the cycle 31 32- `emacs` and `vim` have a feature to allow the user to compile 33 using make and have the editor automatically jump to the line of 34 source code where the compiler detects an error, even when not 35 currently editing the erroneous file. 36 37- The etags feature of `emacs` or tags feature of `vim` enables one 38 to search quickly through a group of user-defined source files 39 (and/or PETSc source files) regardless of the directory in which they 40 are located. [GNU Global](http://www.gnu.org/s/global) is a richer 41 alternative to etags. 42 43- Also, `emacs` and `vim` easily enable: 44 45 - editing files that reside in any directory and retaining one's 46 place within each of them 47 - searching for files in any directory as one attempts to load them 48 into the editor 49 50You might consider using `Microsoft Visual Studio`, `Eclipse` or 51other advanced software development systems. See the {ref}`Users Manual<sec_developer_environments>`. 52 53## Debugging 54 55Most code development for PETSc codes should be done on one processor; 56hence, using a standard debugger such as dbx, gdb, xdbx, etc. is fine. 57For debugging parallel runs we suggest **Totalview** if it is available 58on your machine. Otherwise, you can run each process in a separate 59debugger; this is not the same as using a parallel debugger, but in most 60cases it is not so bad. The PETSc run-time options 61`-start_in_debugger` [-display xdisplay:0] will open separate windows 62and debuggers for each process. You should debug using the debugging 63versions of the libraries (run ./configure with the additional option 64--with-debugging (the default)). 65 66It really pays to learn how to use a debugger; you will end up writing 67more interesting and far more ambitious codes once it is easy for you to 68track down problems in the codes. 69 70## Other suggestions 71 72- Choose consistent and obvious names for variables and functions. 73 (Short variable names may be faster to type, but by using longer 74 names you don't have to remember what they represent since it is 75 clear from the name.) 76- Use informative comments. 77- Leave space in the code to make it readable. 78- Line things up in the code for readability. Remember that any code 79 written for an application will be visited **over and over** again, 80 so spending an extra 20 percent of effort on it the first time will 81 make each of those visits faster and more efficient. 82- Realize that you **will** have to debug your code. **No one** writes 83 perfect code, so always write code that may be debugged and learn how 84 to use a debugger. In most cases using the debugger to track down 85 problems is much faster than using print statements. 86- **Never** hardwire a large problem size into your code. Instead, 87 allow a command line option to run a small problem. We've seen people 88 developing codes who have to wait 15 minutes after starting a run to 89 reach the crashing point; this is an inefficient way of developing 90 code. 91- Develop your code on the simplest machine to which you have access. 92 We have accounts on a variety of large parallel machines, but we 93 write and initially test all our code on laptops or workstations 94 because the user interface is friendlier, and the turn-around time 95 for compiling and running is much faster than for the parallel 96 machines. We use the parallel machines only for large jobs. Since 97 PETSc code is completely portable, switching to a parallel machine 98 from our laptop/workstation development environment simply means 99 logging into another machine -- there are no code or makefile 100 changes. 101- Never develop code directly on a multi-node computing system; your 102 productivity will be much lower than if you developed on a 103 well-organized workstation. 104- Keep your machines' operating systems and compilers up-to-date (or 105 force your systems people to do this :-). You should always work with 106 whatever tools are currently the best available. It may seem that you 107 are saving time by not spending the time upgrading your system, but, 108 in fact, your loss in efficiency by sticking with an outdated system 109 is probably larger than then the time required to keep it up-to-date. 110