CSCI 5161: Introduction to Compilers
Spring 2023, University of Minnesota
Some Comments on Coding Standards and Style

The quality of code and its readability are not dispensible aspects in this course. We may assign 50% or more of the grade to these attributes in particular instances. What is more, readability and clarity of code may allow us to find simple mistakes when we look at it and grade it. This would allow us to give you significant credit for a program that is non-functional but could be working with a few small changes. Note also that the code you write in this course will grow gradually through the term and our finding bugs in earlier parts could help you avoid wasting time later on when such bugs could cause other more difficult parts to break unexpectedly. Life is too short for anyone to be wasting time on inscrutable code. You should not be wanting to do this and you should certainly not expect the instructor or the teaching assistant to do this either.

Here are some simple things to bear in mind about your programs; this is not an exhaustive list. There will be some comments specifically about ML style in the lectures and, in any case, we are expecting that you have had lessons before this course on what does and does not constitute good code.

• Line length: Pick a reasonable maximum line length and stick to it. A yardstick to use: your line length should be such that no line scrolls over when we print out the code. A line length that will ensure this is 80 characters; this is what the instructor typically uses when he writes programs. To guarantee that your code never violates this limit, you might set your editor such that it automatically inserts a line break whenever the number of characters on a line reaches this limit.
• Indentation: Indentation is an extremely important means for conveying information about structure when code is spread over several lines. Determine a logical scheme up-front and always adhere to it when you write your code. For example, when the arguments of a function do not all fit onto the same line as the function name, place them each on separate lines and align them on the left. Similarly, align the different parts of an if-then-else expression and indent nested ones so that the nesting structure is clear from the first glance. Be careful about how you indent because too much white space on the page can also be distracting and thereby take away from readability. If you are new to programming in a Standard ML related language, look on the web for indentation suggestions. If you are using emacs, then the sml mode will also help you make sensible decisions.

• Make indentation independent of environment: Indent in a way that shows up uniformly no matter what the environment. Avoid using tabs because these are notoriously non-uniform: if your environment uses size 2 tabs and ours uses size 8, your code will not be very readable.

• Comments: Comments are an extremely important means for communicating information about the structure of your code. Note, however, that you have to pay careful attention to what you write and also how much for comments to be really useful. Verbose comments, describing obvious aspects or explaining mechanical issues rather than structural ones, often hurt rather than help. A good yardstick to use: every significant function should have a succinct description of what it does, and not how it does it, unless the how is very complicated. Note also that these comments are not expected to be private messages to yourself, they are meant to document the program and help others to understand it. A gauge: if you think you might not be able to understand the comment yourself ten years from when you wrote it, it probably is useless and even harmful.

• Identify the function type at the start of each comment: This is perhaps the most useful kind of comment for your reader. Actually, it is perhaps also extremely helpful to you as a programmer writing down the type of the function before you start writing the code itself. This helps you clearly conceptualize what the function should be doing and you should also check the type SML infers for your function against the type you have put down in your comment to see that you have actually got things right.

• Function length: Do not let functions run on and on. If a function you begin working on seems to be getting too long, think of breaking it up into smaller functional units with clearly defined purposes. There is, of course, no hard and fast rule about how long to make a function and in ML the unit to look at often may be the length of a particular clause in the definition rather than the length of the full collection of clauses. However, if you think consciously about this issue when you are writing your program, it should be clear to you when you are trying to put more functionality into one definition than can be comprehended easily in one go and also when you are making the definition physically too long to be read comfortably.
• Learn about and use library functions: The Standard ML standard library provides you with implementations of many data structures and functions that work on these. For example, it has a large collection of higher-order functions like List.map, List.fold, and their ilk that can be quite useful in compiler writing. Learn about these functions and try to use them where possible. This way, you will be using shared idioms, you will shorten your code and you will not need to re-invent the wheel, something that has the potential of introducing unnecessary errors since the re-invention may not quite work. Browse the standard library early and independently of the code you need to write so that you have information about what is and is not available when you start thinking about your own program.