CS 3358 (Data Structures and Algorithms) by Lee S. Koh
Using putse to Assist in Reformatting Poorly Formatted Code

Imperfect Is Human

In my opinion, it is against the principle of good pedagogy to be providing a program such as putse. 
For I think it tends to mislead students (especially those who are foreign or indifferent to good coding style) into thinking that writing poorly formatted code is condonable; it thus, among others, risks (1) undermining the students' appreciation of the importance of coding in good style, and (2) depriving them of a hands-on opportunity to mold themselves to the habit of coding in good style.
It must therefore be (re-)emphasized that you should make every effort to: 
■ Acquire the familiarity with a set of coding styles that is popularly deemed acceptable (by the programming community).

● See my Programming Style Guide.
■ Cultivate the habit of being mindful of, and striving to abide by, the set of styles as you code.

● Quoted from my Advice on Programming Assignments:


Don't attempt to first write a "sloppy" version during implementation and testing and later re-write a "pretty" version for submission; rather, write only the "pretty" version and take advantage of the "pretty" quality to help you avoid and discover errors.
If you find yourself accomplishing well in the above effort, bravo and you should have little or no need for putse, which is what it should be. 
However, experience tells me that many students tend to not fare very well in the above effort, try I believe they do (but for some, pardon me, perhaps not as hard as they should).
And to keep trying (harder, if I may say) these students should, I must plead.
In the meantime, to help these students minimize losing style points due to poorly formatted code (AND, perhaps more importantly, to dispel the unenviable prospect of "driving up my blood pressure having to read such code"), I have reluctantly (ahem) decided to provide this program called putse to assist them, where applicable, in prettying up their poorly formatted code.

A Panacea putse Is Not

A panacea is a cure-all, a remedy for all diseases.
A piece of poorly-styled code may be suffering from any number of a multitude of shortcomings:
■ Improper indentation
■ Improper alignment
■ Improper spacing
■ Poor choice of identifier names
■ ...
It is too tall an order to attempt to write a style-make-over program that is panacean.
And putse is far from being that.
It is therefore important to understand that putse is only a rather limited code-reformatting helper tool.
CAUTION: You should not think that you won't lose style points because you've run putse on your code.
What putse is capable of, in a nutshell, is to do a decent first-pass (starter) job at aligning and indenting the lines of code of a (poorly formatted) source program.
In other words, putse can be quite useful if you are initiating a make-over effort on a piece of code that is poorly formatted (in terms of alignment and indentation).
In that case, the intent is that you first putse your code (i.e., run putse on your code) and then apply further make-over work manually on the putsed version of your code.
Hopefully, putse will save you quite a bit of the time (and spare you of the tedium and boredom) associated with improving the alignment-indentation aspect of your code.
NOTE: You can also expect putse to do the alignment-indentation work more consistently than us because it won't get tired and bored.
CAUTION: putse does a bad job at indenting a line of code that is a continuation of another line of code.
CAUTION: Because of the preceding shortcoming, putse may actually do you a disservice if your code is already well-indented and well-aligned.
CAUTION: Do not expect putse to render other kinds of style enhancements such as spacing out the various elements of your code.
IN CASE YOU WONDER: putse is an acronym I coined from pretty up to some extent.

Usage Notes

■ The program was compiled using one of CS department's Linux machines.

● It may not run on machines that have different Unix operating systems (including different versions of Linux).

● It definitely will not run on Windows.
■ Steps to use the file for the first time:

● Download the posted file (putse.zip) onto you local machine.

● Uncompress the downloaded file to obtain putse.

● Upload the uncompressed file (putse) to the directory that contains the source file you want to run putse on.

● Do the following while you are in the subdirectory containing the uploaded file (putse):


chmod +x putse

● Run putse as follows:


./putse filename


where filename is the name of the source file you want putsed.

An Example (using a file actually turned in by a student)

■ Code as turned in.

● Yuck!
■ Code putsed.

● Note that many style shortcomings still remain.

● Note the bad job putse did on the continuations of fout statements.
■ Code putsed and manually retouched (perhaps useful to some as an additional coding style reference).

● Main issues addressed during retouching:


► How continuations of fout statements are indented/aligned.


► Shortcomings in spacing and variable naming.


For those that prefer to reformat in Windows


■ Code executable at Windows command prompt window: putse.exe (zipped). 

● A sample poorly styled source file (BadStyle.cpp) is also bundled.
■ How to use:

● Download the file (putseWinCmd.zip) and unzip it (to get putse.exe) into a folder (containing the source file to be putsed) on you local machine.

● Click on Windows Start button followed by the Run... button.
(If you don't see the Run... button after clicking Start button, type run after clicking the Start button and select the Run App.)

● At the ensuing dialog box, type in cmd and hit Enter (or click the OK button).

● Using command-line commands to navigate to the folder containing putse.exe and the source file to be putsed. Below are some useful command-line commands:


► dir /w (list files and folders under the current folder in brief format)


► cd .. (make the immediate parent folder the current folder - go up the directory structure by 1 level)


► cd <SubFolderName> (make the immediate sub-folder named SubFolderName the current folder - go down the directory structure by 1 level)


► d: (switch to drive d)

● Do putse <sourceFileName>


► E.g.: To putse the bundled poorly styled source file (BadStyle.cpp), assuming the file has been unzip into the folder, type putse BadStyle.cpp and hit Enter.